component 1 input manual

User’s Guide

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

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

Internet: [email protected]

Web site: http://www.componentone.com

Sales

E-mail: [email protected]

Telephone: 1.800.858.2739 or 1.412.681.4343 (Pittsburgh, PA USA Office)

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

Trademarks ComponentOne Input for .NET and the ComponentOne Input for .NET logo are trademarks, and ComponentOne is a registered trademark of ComponentOne LLC. All other trademarks used herein are the properties of their respective owners.

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

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

· iii

Table of Contents Table of Contents .......................................................................................... iii Welcome to C1Input for .Net .............................................................................1

Installation .................................................................................................................. 1 Adding the C1Input for .Net Component to the Toolbox .............................................. 2 END-USER LICENSE AGREEMENT FOR COMPONENTONE SOFTWARE........ 2 Licensing FAQs........................................................................................................... 9 Redistributable Files .................................................................................................. 12 Technical Support...................................................................................................... 12 Namespaces .............................................................................................................. 13

Using the C1Input Controls ............................................................................. 15 C1Input Controls....................................................................................................... 15 Data Binding ............................................................................................................. 15 Value and Text: Displaying, Validating and Updating Values...................................... 16 Formatting Data ........................................................................................................ 16 Parsing (Updating) Data ............................................................................................ 26 Culture (Regional) Settings ........................................................................................ 26 Edit Mask.................................................................................................................. 27 Validating Data ......................................................................................................... 28 Editing Date and Time Values.................................................................................... 30 Editing Numeric Values ............................................................................................. 30 Dropdown and Increment Buttons ............................................................................. 30 Custom Dropdown .................................................................................................... 31 Programmatic Formatting, Parsing and Validation...................................................... 31 Error Handling .......................................................................................................... 32 Handling NULL and Empty Values ........................................................................... 34

C1Input Samples ........................................................................................... 35 Visual Basic and C# Samples ..................................................................................... 35

C1Input Tutorials .......................................................................................... 37 Tutorial 1 – Binding C1Input Controls to a Data Source ............................................. 37 Tutorial 2 – Masked Input.......................................................................................... 42 Tutorial 3 – Data Navigation and Actions Using C1DbNavigator................................ 45 Tutorial 4 – Using C1TextBox for Date-Time Input .................................................... 48 Tutorial 5 – Data Validation....................................................................................... 52 Tutorial 6 – Data Formatting and Parsing................................................................... 55 Tutorial 7 - Using C1DateEdit and C1NumericEdit Controls ...................................... 59 Tutorial 8 – Custom Dropdown Form ........................................................................ 62 Tutorial 9 – Editing Numbers in NumericInput Mode................................................. 67

C1Input Reference ......................................................................................... 73 C1DropDownControl Control ................................................................................... 73 C1DateEdit Control................................................................................................... 82 C1NumericEdit Control............................................................................................. 92 C1DbNavigator Control........................................................................................... 103 C1Label Control...................................................................................................... 129 C1PictureBox Control.............................................................................................. 137 C1TextBox Control ................................................................................................. 145 DateEditMonthCalendar Control ............................................................................. 197 NumericEditCalculator Control ............................................................................... 202 FormatInfo Class ..................................................................................................... 205

iv ·

ParseInfo Class ........................................................................................................ 210 Margins Class .......................................................................................................... 220 MaskInfo Class ........................................................................................................ 224 PreValidation Class.................................................................................................. 238 PostValidation Class ................................................................................................ 246 CustomPlaceholder Class ......................................................................................... 252 DropDownForm Class ............................................................................................. 255 PlaceholderCollection Class ..................................................................................... 260 ValueInterval Class .................................................................................................. 264 ValueIntervalCollection Class................................................................................... 267 ErrorInfo Class ........................................................................................................ 272 UIStrings Class ........................................................................................................ 277 C1Input Enumeration Reference............................................................................... 278 C1Input Event Handler Reference ............................................................................ 294 C1Input Event Arguments Reference ........................................................................ 300 C1Input Exception Reference ................................................................................... 307

Index......................................................................................................... 311

Installation · 1

Welcome to C1Input for .Net Welcome to ComponentOne Input for .Net, a set of .Net controls designed to allow developers access to a toolbelt of enhanced visual components. C1Input can help developers display dynamic data in a visual format, manage dataset navigation, display or edit dates, and much more. Using the latest technologies built into Visual Studio.Net, C1Input for .Net completely manages the underlying complexities of a visual programming component, allowing developers to concentrate on important application-specific tasks. If you like Input for .NET, you can check out our other products by visiting our web site at http://www.componentone.com.

C1Input for .Net was designed to be a powerful, versatile, and easy-to-use set of controls. Programmers can use C1Input to create a fully functional data bound application that can be fully interacted with by the user. Professional developers can use the many different controls to accurately display complex sets of data and create user-friendly applications.

C1Input for .Net is a collection of Visual Input Controls for Microsoft Visual Studio.Net. Developed by ComponentOne LLC.

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

We are confident that you'll like Input for .NET. 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

Installation The installation program will create a directory called "ComponentOne Studio.NET" under "Program Files". This directory will contain the following subdirectories:

bin Contains copies of all binaries (DLLs, EXEs) in the ComponentOne Visual Studio.NET package.

Common Contains support and data files that are used by many of the demo programs.

Demos Contains demo projects for all Studio components.

Help Contains online documentation for all Studio components.

C1Input Contains samples and tutorials for the C1Input components.

Other Samples and tutorials for the other Studio components.

http://www.componentone.com/


2 · Welcome to C1Input for .Net

Installing Demonstration Versions If you wish to try C1Input for .NET and do not have a registration key, install the product as usual but do not provide a registration key. The only difference between unregistered (evaluation) and registered (purchased) versions of the software is that the unregistered version will display a banner when it starts executing.

Uninstalling C1Input for .NET To uninstall C1Input for .NET, open the Control Panel application, select the "Add or Remove Programs" option, select C1Input for .NET and click the "Remove" button.

Adding the C1Input for .Net Component to the Toolbox When you install C1Input, the following new components will appear in the Visual Studio’s toolbox customization dialog box:

• C1DataEdit

• C1DbNavigator

• C1DropDownControl

• C1Label

• C1NumericEdit

• C1PictureBox

• C1TextBox

In order to use the C1Input components, you must add them to the Visual Studio Toolbox:

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 C1Input components to appear on its own tab in the Toolbox, select Add Tab from the context menu and type in the tab name, for example, “C1Input”. Select the tab where you want the components 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 components belonging to namespace C1.Win.C1Input.

END-USER LICENSE AGREEMENT FOR COMPONENTONE SOFTWARE

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

I. THIS EULA.

1. Software Covered by this EULA. This EULA governs your use of the ComponentOne, LLC ("C1") software product(s) enclosed or otherwise accompanied herewith (individually and collectively, the "SOFTWARE"). The term "SOFTWARE" includes, to the extent provided by C1: 1) any revisions, updates and/or upgrades thereto; 2) any data, image or executable files, databases, data engines, computer software, or similar items customarily used or distributed with computer software products;

END-USER LICENSE AGREEMENT FOR COMPONENTONE SOFTWARE · 3

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.

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

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

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

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

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

3. Your Distribution License.

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

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

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


C1ReportDesigner Application may be distributed, free of royalties, only in conjunction with the Developed Software.

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

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

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

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

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

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

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

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

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

C1 licenses certain of its separately-licensed products bundled together in a product suite, called the C1 "Studio" product line (the "Studio Products"). The exact separately-licensed products that are bundled into the Studio Products may change from time-to-time in C1's sole discretion. If the SOFTWARE is identified as a C1 "Studio" product, then the SOFTWARE is one of the Studio Products. The SOFTWARE and the Studio Products are revised from time-to-time (meaning, for


example, revised with updates, upgrades and, in the case of Studio products, possibly changes to which specific products are included in the bundle). For you to be entitled to receive any such revisions to the SOFTWARE or the Studio Products, as the case may be, you must have a valid SOFTWARE license or a valid Studio subscription. The original purchaser of the SOFTWARE or of a Studio product receives a one-year subscription from the date of purchase of the SOFTWARE. After one year, the Studio subscription and/or the SOFTWARE license must be renewed to continue to be entitled to receive the SOFTWARE and/or the Studio Products revisions as the case may be.

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

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

III. INTELLECTUAL PROPERTY.

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

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

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

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

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

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.

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


IV. WARRANTIES AND REMEDIES.

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

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

V. MISCELLANEOUS.

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

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

3. Interpretation of this EULA. If for any reason a court of competent jurisdiction finds any provision of this EULA, or any portion thereof, to be unenforceable, that provision of this EULA will be enforced to the maximum extent permissible so as to effect the intent of the parties, and the remainder of this EULA will continue in full force and effect. Formatives of defined terms shall have the same meaning of the defined term. Failure by either party to enforce any provision of this EULA will not be deemed a waiver of future enforcement of that or any other provision. Except as otherwise

Licensing FAQs · 9

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.

Licensing FAQs This section describes the main technical aspects of licensing. It may help the user to understand and resolve licensing problems he may experience when using ComponentOne .NET and ASP.NET products.

What is Licensing? Licensing is a mechanism used to protect intellectual property by ensuring that users are authorized to use software products.

Licensing is not only used to prevent illegal distribution of software products. Many software vendors, including ComponentOne, use licensing to allow potential users to test products before they decide to purchase them.

Without licensing, this type of distribution would not be practical for the vendor or convenient for the user. Vendors would either have to distribute evaluation software with limited functionality, or shift the burden of managing software licenses to customers, who could easily forget that the software being used is an evaluation version and has not been purchased.

How does Licensing Work? ComponentOne uses a licensing model based on the standard set by Microsoft, which works with all types of components.

When a user decides to purchase a product, he receives an installation program and a Serial Number. During the installation process, the user is prompted for the serial number that is saved on the system. (Users can also enter the serial number by clicking the "License" button on the About Box of any ComponentOne product.)

When a licensed component is added to a form or web page, Visual Studio asks the newly created component for licensing information. The component looks for licensing information stored in the system and generates a key, which Visual Studio saves in two files:

1. a "<projectName>.licenses" resource file which contains the actual key and

2. a "licenses.licx" file that contains references to those resources.

These files are automatically added to the project.

Note that the licenses.licx file is usually not shown in the Solution Explorer; it appears if you press the "Show All Files" button in the Solution Explorer's toolbox, or select "Project | Show All Files" from Visual Studio's main menu.

Later, when the component is created at run time, it gets passed the key that was created at design time and can decide whether to simply accept the key, to throw an exception and fail altogether, or to display some information reminding the user that the software has not been licensed.

All ComponentOne products are designed to display licensing information if the product is not licensed. None will throw licensing exceptions and prevent applications from running.


Common Scenarios

Creating components at design time This is the most common scenario and also the simplest: the user adds one or more controls to the form, the licensing information is stored in the licenses.licx file, and the component works.

Note that the mechanism is exactly the same for Windows Forms and Web Forms (ASP.NET) projects.

Creating components at run time This is also a fairly common scenario. You do not need an instance of the component on the form, but would like to create one or more instances at run time.

In this case, the project will not contain a licenses.licx file (or the file will not contain an appropriate key for the component) and therefore licensing will fail.

To fix this problem, add an instance of the component to a form in the project. This will create the licenses.licx file and things will then work as expected. (The component can be removed from the form after the licenses.licx file has been created).

Inheriting from licensed components If a component that inherits from a licensed component is created, the licensing information to be stored in the form is still needed. This can be done in two ways:

1. Add a LicenseProvider attribute to the component.

This will mark the component as licensed. When a component is added to a form, Visual Studio will create and manage the licenses.licx file, and the base class will handle the licensing process as usual. No additional work is needed. For example:

[LicenseProvider(typeof(LicenseProvider))] class MyGrid: C1.Win.C1FlexGrid.C1FlexGrid { // ... }

2. Add an instance of the base component to the form.

This will embed the licensing information into the licenses.licx file as in the previous scenario, and the base component will find it and use it. As before, the extra instance can be deleted after the licenses.licx file has been created.

Using licensed components in console applications When building console applications, there are no forms to add components to, and therefore Visual Studio won't create a licenses.licx file.

In these cases, create a temporary Windows Forms application and add all the desired licensed components to a form. Then close the Windows Forms application and copy the licenses.licx file into the console application project.

Make sure the licensex.licx file is configured as an embedded resource. To do this, right-click the licenses.licx file in the Solution Explorer window and select Properties. In the property window, set the "Build Action" property to "Embedded Resource".

Licensing FAQs · 11

Using licensed components in Visual C++ applications It seems there is a bug in VC++ 2003. The licenses.licx is ignored during the build process, therefore the licensing information is not included in VC++ applications.

To fix this problem, extra steps must be taken to compile the licensing resources and link them to the project. Note the following:

1. Build the C++ project as usual. This should create an exe file and also a licenses.licx file with licensing information in it.

2. Copy the licenses.licx file from the app directory to the target folder (Debug or Release).

3. Copy the C1Lc.exe utility and the licensed dlls to the target folder. (Don't use the standard lc.exe, it has bugs.)

4. Use C1Lc.exe to compile the licenses.licx file. The command line should look like this:

c1lc /target:MyApp.exe /complist:licenses.licx /i:C1.Win.C1FlexGrid.dll

5. Link the licenses into the project. To do this, go back to Visual Studio, right-click the project, select properties, and go to the Linker/Command Line option. Enter the following:

/ASSEMBLYRESOURCE:Debug\MyApp.exe.licenses

6. Rebuild the executable to include the licensing information in the application.

Troubleshooting We try very hard to make the licensing mechanism as unobtrusive as possible, but problems may occur for a number of reasons.

Below is a description of the most common problems and their solutions.

I have a licensed version of a ComponentOne product but I still get the splash screen when I run my project.

If this happens, there must be a problem with the licenses.licx file in the project. It either doesn't exist, contains wrong information, or is not configured correctly.

First, try a full rebuild ("Rebuild All" from the Visual Studio Build menu). This will usually rebuild the correct licensing resources.

If that fails, follow these steps:

1. Open the project and go to the Solution Explorer window.

2. Click the "Show All Files" button on the top of the window.

3. Find the licenses.licx file and delete it.

4. Close the project and reopen it.

5. Open the main form and add an instance of each licensed control.

6. Check the Solution Explorer window, there should be a licenses.licx file there.

7. Rebuild the project using the "Rebuild All" option (not just "Rebuild").


I have a licensed version of a ComponentOne product on my web server but the components still behave as unlicensed.

There is no need to install any licenses on machines used as servers and not used for development.

The components must be licensed on the development machine, therefore the licensing information will be saved into the executable (exe or dll) when the project is built. After that, the application can be deployed on any machine, including web servers.

I downloaded a new build of a component that I have purchased, and now I'm getting the splash screen when I build my projects.

Make sure that the license key is still valid. If you licensed the component over a year ago, your subscription may have expired. In this case, you have two options:

Option 1 - Renew your subscription to get a new license key.

If you choose this option, you will receive a new key that you can use to license the new components (from the installation utility or directly from the About Box).

The new subscription will entitle you to a full year of upgrades and to download the latest maintenance builds directly from http://prerelease.componentone.com/.

Option 2 – Continue to use the components you have.

Subscriptions expire, products do not. You can continue to use the components you received or downloaded while your subscription was valid.

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

• C1.Common.dll

• C1.Win.C1Input.dll

Site licenses are available for groups of multiple developers. Please contact [email protected] for details.

Technical Support C1Input for .Net 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 C1Input users:

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

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

http://prerelease.componentone.com/

mailto:[email protected]


Namespaces · 13

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

[email protected]

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

Namespaces Namespaces organize the objects defined in an assembly. Assemblies can contain multiple namespaces, which can in turn contain other namespaces. Namespaces prevent ambiguity and simplify references when using large groups of objects such as class libraries.

The namespace for the C1Input controls:

• C1.Win.C1Input

The following code fragment shows how to declare a C1TextBox control, for example, using the fully qualified name for this class:

• Visual Basic

Dim textbox As C1.Win.C1Input.C1TextBox

• C#

C1.Win.C1Input.C1TextBox textbox;

• Delphi

textbox: C1.Win.C1Input.C1TextBox;

Namespaces address a problem sometimes known as namespace pollution, in which the developer of a class library is hampered by the use of similar names in another library. These conflicts with existing components are sometimes called name collisions.

For example, if you create a new class named FormatInfo, you can use it inside the project without qualification. However, the C1Input assembly also implements a class called FormatInfo. So, to use the FormatInfo class in the same project, a fully qualified reference must be used to make the reference unique. If the reference is not unique, Visual Studio .NET produces an error stating that the name is ambiguous.

mailto:[email protected]

http://www.componentone.com/support

http://www.componentone.com/newsgroups


Fully qualified names are object references that are prefixed with the name of the namespace where the object is defined. Objects defined in other projects can be used if a reference to the class is created (by choosing Add Reference from the Project menu) and then the fully qualified name for the object can be used in the code.

Fully qualified names prevent naming conflicts because the compiler can always determine which object is being used. However, the names themselves can get long and cumbersome. To get around this, use the Imports statement (using in C#) to define an alias — an abbreviated name that can be used in place of a fully qualified name. For example, the following code snippet creates aliases for two fully qualified names, and uses these aliases to define two objects:

• Visual Basic

Imports C1FormatInfo = C1.Win.C1Input.FormatInfo Imports MyFormatInfo = MyProject.FormatInfo Dim fi1 As C1FormatInfo Dim fi2 As MyFormatInfo

• C#

using C1FormatInfo = C1.Win.C1Input.FormatInfo; using MyFormatInfo = MyProject.FormatInfo; C1FormatInfo fi1; MyFormatInfo fi2;

• Delphi

uses C1.Win.C1Input, MyProject; type TC1FormatInfo = C1.Win.C1Input.FormatInfo; TMyFormatInfo = MyProject.FormatInfo; var fi1: TC1FormatInfo; fi2: TMyFormatInfo;

If the Imports statement is used without an alias, all the names in that namespace can be used without qualification provided they are unique to the project.

As a warning, unless specified explicitly in code, it is taken for granted that the statement has been specified. This applies only to small code samples. Tutorials and other longer samples will specify complete qualifiers.

• Visual Basic

Imports C1.Win.C1Input

• C#

using C1.Win.C1Input;

• Delphi

uses C1.Win.C1Input;

C1Input Controls · 15

Using the C1Input Controls The following sections describe various aspects of using C1Input controls.

C1Input Controls The current version of C1Input contains six controls:

C1TextBox The main data bound control used for entering and editing information of any data type in a text form. Supports data formatting, edit mask, data validation and other features. C1TextBox also supports formatted and masked editing of all data types, including special features for date-time formats. Apart from being the main data editor control, C1TextBox also serves as the base class for specialized controls such as C1NumericEdit and C1DateEdit. C1TextBox derives from the standard System.Windows.Forms.TextBox control.

C1NumericEdit Data bound control derived from C1TextBox specialized for editing numeric values. In addition to C1TextBox functionality, C1NumericEdit supports a dropdown calculator and an up-down (spin) button that can be used to increment/decrement the value.

C1DateEdit Data bound control derived from C1TextBox specialized for editing date and time values. In addition to C1TextBox functionality, C1DateEdit supports a dropdown calendar and an up-down (spin) button for changing the value.

C1Label Read-only data bound control that displays formatted data. C1Label derives from the standard System.Windows.Forms.Label control.

C1PictureBox Data bound control which shows picture images stored in a data source field, derives from System.Windows.Forms.PictureBox.

C1DbNavigator Data bound control which provides buttons for convenient navigation over data source rows. It enables movement to the first, last, previous and next row and common data actions such as updating the data source and refreshing data.

Data Binding C1Input controls can function both in unbound and in bound mode. In bound mode, a control’s Value is bound to a data source field.

C1Input controls support data binding to all .NET data sources. This includes ADO.NET data source objects such as DataTable, DataView and DataSet, and also ComponentOne DataObjects components such as C1ExpressTable, C1ExpressView, C1ExpressConnection, C1DataView, C1DataTableSource and C1DataSet.

For details about creating ADO.Net data source objects, please refer to the .NET Framework documentation.

For details about using ComponentOne DataObjects, see the C1DataObjects documentation included in the ComponentOne Studio for .NET. ComponentOne DataObjects is a data framework, a part of ComponentOne Studio for .NET, enhancing ADO.NET in many ways.

To bind a C1Input control to a data source field, assign the data source object to the control's DataSource property, then assign a field of the data source object to the control’s DataField property. You can set the DataSource and DataField properties at run time as well as at design time. At design time, you can select the data source object and its field from the lists of available data sources and their fields provided by the DataSource/DataField property combo boxes.

16 · Using the C1Input Controls

After you bind the control to a data filed, the DataType property is automatically set to the data type of the field it is bound to. In most cases, this setting is what you need. However, sometimes you need different types for the control and the field. For example, you might have a string field containing dates. In such cases, you can set the DataType property after binding and use the BindingFormatting/BindingParsing events to convert data to/from the control’s DataType when it is written from/saved to the data source.

The DataSource/DataField properties are used to bind the Value property of the control to a data source field. The Value property is the main property of a C1Input control. It holds and returns a value with of a specific data type. In addition, you have the freedom to bind other properties of the control to other data sources and fields, as in any other WinForms control, using the DataBindings property. This functionality is not C1Input-specific; it is supported by the .NET Framework for all controls.

Caution:

Do not use properties other than the Value property under DataBinding to bind the control’s value to a field, use the DataSource/DataField properties instead (or use Value in DataBindings). For example, although it is possible to bind the Text property to a field, the result will not be the same as binding the Value property.

Value and Text: Displaying, Validating and Updating Values The Value property is the main property of a C1Input control and is responsible for returning and accepting a value with a specific DataType.

When the control is not in EditMode, the Text shown by the control will display its current Value (except when TextDetached = True) in a properly formatted form, see Formatting Data (page 16).

If the control is not read-only, it automatically switches to EditMode when it receives input focus, provided that TextDetached = False. Input focus refers to when the input window of the control receives focus. In edit mode, the control’s text is edited by the user while the Value remains unchanged until the editing ends. When the user attempts to leave the control, (i.e. move the input focus elsewhere), the Value property is updated with the Text entered by the user.

The process of updating the Value involves three main actions: parsing, validation and updating. Since the Value property is typed (according to the control’s current DataType), the process starts from the action of parsing the Text string, and converting it to the correct DataType. If necessary, the entered text can be validated at this point using string-based validation techniques such as pattern matching and regular expressions, see Validating Data (page 28). Once a typed value is obtained, it passes the PostValidation check, where it can be matched against a list of predefined values, maximum and minimum values and intervals, or validated programmatically in the PostValidating event. After validation, the new value is assigned to the Value property, and then the Value property is updated to the data source.

Updating the Value normally occurs when the user tries to move the input focus out of the control or makes a mouse click outside of the control. However, it can also be triggered programmatically, by calling the UpdateValueWithCurrentText method at any time.

Setting the TextDetached property to True (it is False by default) forces the control into a special mode. If TextDetached = True, the link between Value and Text is disabled, changing Value does not update Text, and changing Text does not update Value even when the control loses input focus. The Text property becomes independent of the Value property. This mode is useful when you want full programmatic control over updating the Text and Value.

Formatting Data C1Input controls support a rich formatting model which enables developers to customize the appearance of a control’s text in almost any way imaginable. The main function of Formatting is to display a string Text representation of a typed or stored Value.

Formatting Data · 17

Formatting is controlled by the FormatType property, see Format types (page 17). Its enumerated values define data will be formatted in the control. Some of the options correspond to .NET standard format specifiers for numeric and date-time types, for example, StandardNumber and LongDate, see “Formatting Types” in the .NET Framework documentation.

One FormatType option, CustomFormat, corresponds to the case of a custom format specifier as defined in the .NET Framework documentation, the specifier itself is determined by the CustomFormat property. For example, CustomFormat = “##,###.###” produces numbers with at most five digits before and three digits after decimal point. See Custom format specifiers (page 19) for details.

There is also a special FormatType option, UseEvent, which delegates the formatting to the Formatting event.

The ability to represent NULL values (System.DBNull) is controlled by the NullText and EmptyAsNull properties.

Sometimes you may find it useful to trim leading and/or trailing spaces when showing the formatted value. You can use the TrimStart and TrimEnd properties for that.

It is possible to specify two different formats, one for display (when the control is read-only or is not in the edit mode), and another for edit mode, see Value and Text: Displaying, Validating and Updating Values (page 16 )to find more information about edit mode.

These two formatting modes are governed by the DisplayFormat and EditFormat properties. By default, both of them inherit from the control’s properties. To assign specific FormatType, CustomFormat or other formatting property (see FormatInfo class) for a specific mode, expand the DisplayFormat or EditFormat nodes, and change the (Inherit) flags and set the desired sub-property.

Format types By default (FormatType = DefaultFormat), the Text is obtained by applying the standard ToString() method of the current DataType to the typed Value (more exactly, if the type has a type converter, TypeConverter.ToString() is used). This conversion (as all others) uses the regional settings provided by the CultureInfo property.

Formatting is controlled by the FormatType property. Its enumerated values define the method of formatting values. Some of the options correspond to standard format specifiers for numeric and date-time types, for example, the StandardNumber and LongDate formats, for more information see “Formatting Types” in the .NET Framework documentation. One option, CustomFormat, corresponds to the case of a custom format specifier as defined in the .NET Framework documentation, the specifier itself is determined by the CustomFormat property. There is also an option delegating formatting to code in an event. The following table describes the list of available options:

DefaultFormat Conversion using TypeConverter.ConvertToString().

UseEvent Conversion performed by user code in the Formatting (or Parsing) event.

CustomFormat Formatting uses the string assigned to the CustomFormat property. Parsing uses NumberStyle, DateTimeStyle, and CustomFormat properties.

GeneralNumber The number is converted to the most compact decimal form, using fixed point or scientific notation.

Currency The number is converted to a string that represents a currency amount.


FixedPoint The number is converted to a string of the form “-ddd.ddd…” where each 'd' indicates a digit (0-9). The string starts with a minus sign if the number is negative. The numeric precision is given by the property NumberFormatInfo.NumberDecimalDigits of the specified culture.

StandardNumber The number is converted to a string of the form "-d,ddd,ddd.ddd…", where each 'd' indicates a digit (0-9). The string starts with a minus sign if the number is negative. Thousand separators are inserted between each group of three digits to the left of the decimal point. The numeric precision is given by the property NumberFormatInfo.NumberDecimalDigits of the specified culture.

Percent The number is converted to a string that represents a percent as defined by the NumberFormatInfo.PercentNegativePattern property or the NumberFormatInfo.PercentPositivePattern property. If the number is negative, the string produced is defined by the PercentNegativePattern and starts with a minus sign. The converted number is multiplied by 100 in order to be presented as a percentage. The default numeric precision given by NumberFormatInfo is used.

Scientific The number is converted to a string of the form "-d.ddd…E+ddd" or "-d.ddd…e+ddd", where each 'd' indicates a digit (0-9). The string starts with a minus sign if the number is negative. One digit always precedes the decimal point. The exponent always consists of a plus or minus sign and a minimum of three digits. The exponent is padded with zeros to meet this minimum, if required.

RoundTrip The round-trip specifier guarantees that a numeric value converted to a string will be parsed back into the same numeric value. This format is supported by floating-point types only.

Integer Displays number as a string that contains the value of the number in Decimal (base 10) format. This format is supported for integral types only.

Hexadecimal The number is converted to a string of hexadecimal digits. This format is supported for integral types only.

YesNo Converts to Boolean and shows No for false, Yes for true.

TrueFalse Converts to Boolean and shows True or False.

OnOff Converts to Boolean and shows Off for false, On for true.

GeneralDate General date/time pattern (short time).

LongDate Displays a date according to specified CultureInfo's long date format.

MediumDate Displays a date using the medium date format ("dd-MMM-yy").

ShortDate Displays a date using specified CultureInfo's short date format.

LongTime Displays a time using your locale's long time format; includes hours, minutes, seconds.

MediumTime Displays time in 12-hour format using hours and minutes and the AM/PM designator ("hh:mm tt").


ShortTime Displays a time using the 24-hour format, for example, 17:45.

LongDateShortTime Displays the long date and short time according to specified CultureInfo's format.

LongDateLongTime Displays the long date and long time according to specified CultureInfo's format.

ShortDateShortTime Displays the short date and short time according to specified CultureInfo's format.

ShortDateLongTime Displays the short date and long time according to specified CultureInfo's format.

MonthAndDay Displays the month and the day of a date.

DateAndTimeGMT Formats the date and time as Greenwich Mean Time (GMT).

DateTimeSortable Formats the date and time as a sortable index.

GMTSortable Formats the date and time as a GMT sortable index.

LongDateTimeGMT Formats the date and time with the long date and long time as GMT.

YearAndMonth Formats the date as the year and month.

Custom Format Specifiers Setting FormatType = CustomFormat corresponds to the case of a custom format specifier as defined in the .NET Framework documentation, the specifier itself is determined by the CustomFormat property. In the CustomFormat string you define the format desired using special characters for numeric and date-time types as presented in the following tables. For details, see “Custom Numeric Format Strings” and “Date and Time Format Strings” in the .NET Framework documentation.

Numeric Custom Format Specifiers

0 Zero placeholder If the value being formatted has a digit in the position where the '0' appears in the format string, then that digit is copied to the output string. The position of the leftmost '0' before the decimal point and the rightmost '0' after the decimal point determines the range of digits that are always present in the output string.

# Digit placeholder If the value being formatted has a digit in the position where the '#' appears in the format string, then that digit is copied to the output string. Otherwise, nothing is stored in that position in the output string. Note that this specifier never displays the '0' character if it is not a significant digit, even if '0' is the only digit in the string. It will display the '0' character if it is a significant digit in the number being displayed.


. Decimal point The first '.' character in the format string determines the location of the decimal separator in the formatted value; any additional '.' characters are ignored. The actual character used as the decimal separator is determined by the NumberDecimalSeparator property of the NumberFormatInfo object that controls formatting.

, Thousand separator and number scaling

The ',' character serves two purposes. First, if the format string contains a ',' character between two digit placeholders (0 or #) and to the left of the decimal point if one is present, then the output will have thousand separators inserted between each group of three digits to the left of the decimal separator. The actual character used as the decimal separator in the output string is determined by the NumberGroupSeparator property of the current NumberFormatInfo object that controls formatting.

Second, if the format string contains one or more ',' characters immediately to the left of the decimal point, then the number will be divided by the number of ',' characters multiplied by 1000 before it is formatted. For example, the format string '0,,' will represent 100 million as simply 100. Use of the ',' character to indicate scaling does not include thousand separators in the formatted number. Thus, to scale a number by 1 million and insert thousand separators you would use the format string '#,##0,,'.

% Percentage placeholder

The presence of a '%' character in a format string causes a number to be multiplied by 100 before it is formatted. The appropriate symbol is inserted in the number itself at the location where the '%' appears in the format string. The percent character used is dependent on the current NumberFormatInfo class.

E0

E+0

E-0

e0

e+0

e-0

Scientific notation If any of the strings 'E', 'E+', 'E-', 'e', 'e+', or 'e-' are present in the format string and are followed immediately by at least one '0' character, then the number is formatted using scientific notation with an 'E' or 'e' inserted between the number and the exponent. The number of '0' characters following the scientific notation indicator determines the minimum number of digits to output for the exponent. The 'E+' and 'e+' formats indicate that a sign character (plus or minus) should always precede the exponent. The 'E', 'E-', 'e', or 'e-' formats indicate that a sign character should only precede negative exponents.

'ABC'

"ABC"

Literal string Characters enclosed in single or double quotes are copied to the output string literally, and do not affect formatting.

; Section separator The ';' character is used to separate sections for positive, negative, and zero numbers in the format string.


True|False Boolean format String representation for two Boolean values, True and False separated with ‘|’, Strings “True” and “False” can be replaced with any other strings representing the two Boolean values.

Other All other characters All other characters are copied to the output string as literals in the position they appear.

Examples:

CustomFormat Value Output ##### 123 123 00000 123 00123 (###) ### - #### 1234567890 (123) 456 – 7890 #.## 1.2 1.2 0.00 1.2 1.20 00.00 1.2 01.20 #,# 1234567890 1,234,567,890 #,, 1234567890 1235 #,,, 1234567890 1 #,##0,, 1234567890 1,235 #0.##% 0.086 8.6% 0.###E+0 86000 8.6E+4 0.###E+000 86000 8.6E+004 0.###E-000 86000 8.6E004 [##-##-##] 123456 [12-34-56] ##;(##) 1234 1234 ##;(##) -1234 (1234)

Date-Time Custom Format Specifiers

d Displays the current day of the month, measured as a number between 1 and 31, inclusive. If the day is a single digit only (1-9), then it is displayed as a single digit.

Note that if the 'd' format specifier is used alone, without other custom format strings, it is interpreted as the standard short date pattern format specifier. If the 'd' format specifier is passed with other custom format specifiers, it is interpreted as a custom format specifier.

dd Displays the current day of the month, measured as a number between 1 and 31, inclusive. If the day is a single digit only (1-9), it is formatted with a preceding 0 (01-09).


ddd Displays the abbreviated name of the day for the specified DateTime object. If a specific valid format provider (a non-null object that implements IFormatProvider with the expected property) is not supplied, then the AbbreviatedDayNames property of the DateTimeFormat object and its current culture associated with the current thread is used. Otherwise, the AbbreviatedDayNames property from the specified format provider is used.

dddd (plus any number of additional "d" characters)

Displays the full name of the day for the specified DateTime object. If a specific valid format provider (a non-null object that implements IFormatProvider with the expected property) is not supplied, then the DayNames property of the DateTimeFormat object and its current culture associated with the current thread is used. Otherwise, the DayNames property from the specified format provider is used.

f Displays seconds fractions represented in one digit.

Note that if the 'f' format specifier is used alone, without other custom format strings, it is interpreted as the full (long date + short time) format specifier. If the 'f' format specifier is passed with other custom format specifiers, it is interpreted as a custom format specifier.

ff Displays seconds fractions represented in two digits.

fff Displays seconds fractions represented in three digits.

ffff Displays seconds fractions represented in four digits.

fffff Displays seconds fractions represented in five digits.

ffffff Displays seconds fractions represented in six digits.

fffffff Displays seconds fractions represented in seven digits.

g or gg (plus any number of additional "g" characters)

Displays the era (A.D. for example) for the specified DateTime object. If a specific valid format provider (a non-null object that implements IFormatProvider with the expected property) is not supplied, then the era is determined from the calendar associated with the DateTimeFormat object and its current culture associated with the current thread.

Note that if the 'g' format specifier is used alone, without other custom format strings, it is interpreted as the standard general format specifier. If the 'g' format specifier is passed with other custom format specifiers, it is interpreted as a custom format specifier.

h Displays the hour for the specified DateTime object in the range 1-12. The hour represents whole hours passed since either midnight (displayed as 12) or noon (also displayed as 12). If this format is used alone, then the same hour before or after noon is indistinguishable. If the hour is a single digit (1-9), it is displayed as a single digit. No rounding occurs when displaying the hour. For example, a DateTime of 5:43 returns 5.

hh, hh (plus any number of additional "h" characters)

Displays the hour for the specified DateTime object in the range 1-12. The hour represents whole hours passed since either midnight (displayed as 12) or noon (also displayed as 12). If this format is used alone, then the same hour before or after noon is indistinguishable. If the hour is a single digit (1-9), it is formatted with a preceding 0 (01-09).


H Displays the hour for the specified DateTime object in the range 0-23. The hour represents whole hours passed since midnight (displayed as 0). If the hour is a single digit (0-9), it is displayed as a single digit.

HH, HH (plus any number of additional "H" characters)

Displays the hour for the specified DateTime object in the range 0-23. The hour represents whole hours passed since midnight (displayed as 0). If the hour is a single digit (0-9), it is formatted with a preceding 0 (01-09).

m Displays the minute for the specified DateTime object in the range 0-59. The minute represents whole minutes passed since the last hour. If the minute is a single digit (0-9), it is displayed as a single digit.

Note that if the 'm' format specifier is used alone, without other custom format strings, it is interpreted as the standard month day pattern format specifier. If the 'm' format specifier is passed with other custom format specifiers, it is interpreted as a custom format specifier.

mm, mm (plus any number of additional "m" characters)

Displays the minute for the specified DateTime object in the range 0-59. The minute represents whole minutes passed since the last hour. If the minute is a single digit (0-9), it is formatted with a preceding 0 (01-09).

M Displays the current month, measured as a number between 1 and 12, inclusive. If the month is a single digit (1-9), it is displayed as a single digit.

Note that if the 'M' format specifier is used alone, without other custom format strings, it is interpreted as the standard month day pattern format specifier. If the 'M' format specifier is passed with other custom format specifiers, it is interpreted as a custom format specifier.

MM Displays the current month, measured as a number between 1 and 12, inclusive. If the month is a single digit (1-9), it is formatted with a preceding 0 (01-09).

MMM Displays the abbreviated name of the month for the specified DateTime object. If a specific valid format provider (a non-null object that implements IFormatProvider with the expected property) is not supplied, the AbbreviatedMonthNames property of the DateTimeFormat object and its current culture associated with the current thread is used. Otherwise, the AbbreviatedMonthNames property from the specified format provider is used.

MMMM Displays the full name of the month for the specified DateTime object. If a specific valid format provider (a non-null object that implements IFormatProvider with the expected property) is not supplied, then the MonthNames property of the DateTimeFormat object and its current culture associated with the current thread is used. Otherwise, the MonthNames property from the specified format provider is used.

s Displays the seconds for the specified DateTime object in the range 0-59. The second represents whole seconds passed since the last minute. If the second is a single digit (0-9), it is displayed as a single digit only.

Note that if the 's' format specifier is used alone, without other custom format strings, it is interpreted as the standard sortable date/time pattern format specifier. If the 's' format specifier is passed with other custom format specifiers, it is interpreted as a custom format specifier.


ss, ss (plus any number of additional "s" characters)

Displays the seconds for the specified DateTime object in the range 0-59. The second represents whole seconds passed since the last minute. If the second is a single digit (0-9), it is formatted with a preceding 0 (01-09).

t Displays the first character of the A.M./P.M. designator for the specified DateTime object. If a specific valid format provider (a non-null object that implements IFormatProvider with the expected property) is not supplied, then the AMDesignator (or PMDesignator) property of the DateTimeFormat object and its current culture associated with the current thread is used. Otherwise, the AMDesignator (or PMDesignator) property from the specified IFormatProvider is used. If the total number of whole hours passed for the specified DateTime is less than 12, then the AMDesignator is used. Otherwise, the PMDesignator is used.

Note that if the 't' format specifier is used alone, without other custom format strings, it is interpreted as the standard long time pattern format specifier. If the 't' format specifier is passed with other custom format specifiers, it is interpreted as a custom format specifier.

tt, tt (plus any number of additional "t" characters)

Displays the A.M./P.M. designator for the specified DateTime object. If a specific valid format provider (a non-null object that implements IFormatProvider with the expected property) is not supplied, then the AMDesignator (or PMDesignator) property of the DateTimeFormat object and its current culture associated with the current thread is used. Otherwise, the AMDesignator (or PMDesignator) property from the specified IFormatProvider is used. If the total number of whole hours passed for the specified DateTime is less than 12, then the AMDesignator is used. Otherwise, the PMDesignator is used.

y Displays the year for the specified DateTime object as a maximum two-digit number. The first two digits of the year are omitted. If the year is a single digit (1-9), it is displayed as a single digit.

yy Displays the year for the specified DateTime object as a maximum two-digit number. The first two digits of the year are omitted. If the year is a single digit (1-9), it is formatted with a preceding 0 (01-09).

yyyy Displays the year for the specified DateTime object, including the century. If the year is less than four digits in length, then preceding zeros are appended as necessary to make the displayed year four digits long.

z Displays the time zone offset for the system's current time zone in whole hours only. The offset is always displayed with a leading or trailing sign (zero is displayed as '+0'), indicating hours ahead of Greenwich mean time (+) or hours behind Greenwich mean time (-). The range of values is –12 to +13. If the offset is a single digit (0-9), it is displayed as a single digit with the appropriate leading sign. The setting for the time zone is specified as +X or –X where X is the offset in hours from GMT. The displayed offset is affected by daylight time.

zz Displays the time zone offset for the system's current time zone in whole hours only. The offset is always displayed with a leading or trailing sign (zero is displayed as '+00'), indicating hours ahead of Greenwich mean time (+) or hours behind Greenwich mean time (-). The range of values is –12 to +13. If the offset is a single digit (0-9), it is formatted with a preceding 0 (01-09) with the appropriate leading sign. The setting for the time zone is specified as +X or –X where X is the offset in hours from GMT. The displayed offset is affected by daylight time.


zzz, zzz (plus any number of additional "z" characters)

Displays the time zone offset for the system's current time zone in hours and minutes. The offset is always displayed with a leading or trailing sign (zero is displayed as '+00:00'), indicating hours ahead of Greenwich mean time (+) or hours behind Greenwich mean time (-). The range of values is –12 to +13. If the offset is a single digit (0-9), it is formatted with a preceding 0 (01-09) with the appropriate leading sign. The setting for the time zone is specified as +X or –X where X is the offset in hours from GMT. The displayed offset is affected by daylight time.

: Time separator.

/ Date separator.

" Quoted string. Displays the literal value of any string between two quotation marks preceded by the escape character (/).

' Quoted string. Displays the literal value of any string between two " ' " characters.

%c Where c is a standard format character, displays the standard format pattern associated with the format character.

\c Where c is any character, the escape character displays the next character as a literal. The escape character cannot be used to create an escape sequence (like "\n" for new line) in this context.

| Section separator. Custom date-time format can contain multiple format strings separated with ‘|’, This feature allows to specify multiple input formats for date-time values. Only the first format string is used to format value, convert date-time to string. Performing the inverse conversion (parsing) from string to date-time, a string will be recognized (parsed) if it satisfies one of the allowed formats.

Any other character

Other characters are written directly to the output string as literals.

Examples:

Format specifiers Current culture Time zone Output d, M en-US GMT 12, 4 d, M es-MX GMT 12, 4 d MMMM en-US GMT 12 April d MMMM es-MX GMT 12 Abril dddd MMMM yy gg en-US GMT Thursday April 01

A.D. dddd MMMM yy gg es-MX GMT Jueves Abril 01 DC h , m: s En-US GMT 6 , 13: 12 hh,mm:ss En-US GMT 06,13:12 HH-mm-ss-tt En-US GMT 06-13-12-AM hh:mm, G\MT z En-US GMT 05:13 GMT +0


hh:mm, G\MT z En-US GMT +10:00 05:13 GMT +10 hh:mm, G\MT zzz En-US GMT 05:13 GMT +00:00 hh:mm, G\MT zzz En-US GMT –9:00 05:13 GMT -09:00

Parsing (Updating) Data Data modified by the end user in a C1Input control is converted from a string to a typed Value. Converting data from a string representation is called parsing. It is the opposite of formatting. Parsing is controlled by the ParseInfo property. The ParseInfo property provides access to the ParseInfo Class that contains sub-properties that control different aspects of parsing.

For the most part, you will probably be satisfied with the default parsing that is performed according to the format specification, as it is the inverse of formatting. By default, the same format property value is used for parsing as for formatting. However, you can change any of aspects of how the control parses, by expanding the ParseInfo property, changing the (Inherit) flags, and setting desired properties.

The ParseInfo class also contains two flag properties, NumberStyle and DateTimeStyle, which enable you to fine-tune parsing by allowing or disallowing white spaces and special characters in input strings for numeric and date-time data. For more information see the ParseInfo class in the reference section.

By setting the FormatType property to UseEvent, you can make your parsing entirely custom through writing code to handle the parsing action in the Parsing event.

Note:

Parsing is not performed in DateTimeInput and NumericInput modes. It is unnecessary, because in this case the content is already a typed value (date/time or number), so there is no need to parse a string to obtain the value.

Culture (Regional) Settings Regional settings affect almost all aspects of C1Input functionality. Formatting, parsing, validating data and performing masked input all depend on cultural settings for string comparison, numeric and date time formats and special characters, such as decimal point character, etc. See description of the CultureInfo class in .NET Framework documentation for details on culture-specific settings.

C1Input controls use the following properties to define CultureInfo:

The Culture property defines what culture is used by the control. It is an integer ID with a list of all cultures available at design time. The default is 0 – Current Culture, which is the current culture used by the application containing the control. Culture name is available in a read-only property CultureName.

The CultureInfo property contains all the settings, the CultureInfo object corresponding to the specified culture ID.

The Boolean UserCultureOverride property allows the culture settings to be overridden by the end user regional settings.

You can change any settings in the CultureInfo programmatically. To enable this, C1Input controls fire the CultureInfoSetup event at startup and whenever the Culture property is set. Handling this event you can fine-tune various CultureInfo settings. For example, you may want to set CultureInfo.DateTimeFormat.FirstDayOfWeek according to your application needs.

Another setting affecting most of C1Input functionality is the Boolean CaseSensitive property (although it is not culture-related). Case sensitivity is used in string comparisons. C1Input controls have a CaseSensitive

Edit Mask · 27

property that defines the default case sensitivity for all operations. You can override this setting in most classes controlling particular functionality, such as ParseInfo, PreValidation, PostValidation, etc.

Edit Mask C1Input controls support masked input when you set the EditMask property to a mask string. If you define an edit mask, each character position in the control maps to either a special placeholder or a literal character. Literal characters, or literals, can give visual cues about the type of data being used. For example, the parentheses surrounding the area code of a telephone number and dashes are literals: (412)-123-4567. The edit mask prevents you from entering invalid characters into the control and provides other enhancements of the user interface.

To enable masked input, set the EditMask property to a mask string composed of placeholders and literals, see the table of available placeholders below. You can also define your own placeholders, using the MaskInfo.CustomPlaceholders collection.

Although setting EditMask is enough in simple cases, there is also a MaskInfo property containing sub-properties controlling various important aspects of masked input. One of them is the CustomPlaceholders collection mentioned above. Some of the others are:

AutoTabWhenFilled If True, focus automatically moves to the next control when the mask is filled. Default: False.

PromptChar Character displayed on empty positions. Default: '_'.

SaveBlanks If True, the stored text includes blank positions as StoredEmptyChar. Default: False.

SaveLiterals If True (default), the stored text (StoredContent) includes literals.

ShowLiterals Enumeration controlling the way in which literals appear while the user types. They can appear always, or never, or as the user reaches a literal while typing.

SkipOptional If True (default), optional mask positions are automatically skipped until the first position allowing the typed character.

StoredEmptyChar Character stored in empty mask positions. Default: '_'.

See the MaskInfo class for the complete list of mask-related properties.

If ShowLiterals = FreeFormatEntry, optional mask positions can be completely omitted, there is no need to fill them with blank characters. Mask characters (placeholders) used in C1Input are similar to those used in Microsoft Access and Microsoft ActiveX MaskedEdit control (and more placeholders can be defined using the using the MaskInfo.CustomPlaceholders collection):

# Digit placeholder permits a numeric character or a plus or minus sign in this position (entry optional).

. Decimal placeholder. The actual character used is the one specified as the decimal placeholder in your international settings. This character is treated as a literal for masking purposes.


, Thousands separator. The actual character used is the one specified as the thousands separator in your international settings. This character is treated as a literal for masking purposes.

: Time separator. The actual character used is the one specified as the time separator in your international settings. This character is treated as a literal for masking purposes.

/ Date separator. The actual character used is the one specified as the date separator in your international settings. This character is treated as a literal for masking purposes.

\ Treat the next character in the mask string as a literal. This allows you to include the #, &, A, … characters in the mask. This character is treated as a literal for masking purposes.

& Character placeholder (entry required). Any character is permitted.

> Convert all the characters that follow to uppercase.

< Convert all the characters that follow to lowercase.

~ Turns off the previous < or >.

! Causes the optional characters that follow in the edit mask to display from right to left, rather than from left to right. So, blanks appear on the left.

^ Turns off the previous ! character. After ^, blanks appear on the right.

A Alphanumeric character placeholder (entry required). For example: a – z, A – Z, or 0 – 9.

a Alphanumeric character placeholder (entry optional).

0 Digit placeholder (entry required). For example: 0 – 9.

9 Digit placeholder (entry optional).

C Character or space placeholder (entry optional). Any character is permitted.

L Letter placeholder (entry required). For example: a – z or A – Z.

? Letter placeholder (entry optional).

\n New line literal. It is applicable when Multiline = True.

" All characters in a string enclosed in double quotes are considered as literals.

Literal All other symbols are displayed as literals; that is, as themselves.

Example:

The telephone number mentioned above, (412) 123-4567 can be represented with a mask EditMask = “(000) 000-0000”.

Validating Data C1Input controls support data validation both of the raw input string (PreValidation) and of the typed value entered by the user (PostValidation). See Value and Text: Displaying, Validating and Updating Values (page 16 )for explanation of the validation process.

Validating Data · 29

Input String Validation (PreValidation) Input string validation is controlled by the PreValidation property. The PreValidation class allows you to specify validation rules either as wildcard pattern strings or regular expression strings. All rules (strings) are specified in the PatternString property. Multiple rules (sub-strings) are separated by the ItemSeparator ('|' by default).

The Validation property defines how the PatternString is interpreted.

ExactList PatternString contains a list of possible values separated by ItemSeparator.

PreValidatingEvent The PreValidating event is being used in validation.

Wildcards PatternString contains a list of wildcard patterns separated by the ItemSeparator. The following characters are reserved in a pattern: ? (any single character), # (any single digit), * (zero or more characters), \ (escape). You can also define your own custom pattern characters using the CustomPlaceholders property.

RegexPattern PatternString contains a regular expression.

Using the PreValidatingEvent option, you can perform input string validation in code, in the PreValidating event. For more information see the event description.

If you use regular expressions, the RegexPattern option, there is also a RegexOptions property that is sometimes needed to set flags affecting regular expression functionality.

Note:

Input string validation (PreValidation) is not used in DateTimeInput and NumericInput modes. When DateTimeInput or NumericInput modes are active is Typed value validation (PostValidation) (page 29) is performed.

Examples:

Validation = ExactList, PatternString = “red|green|blue”: Input string must be one of the three permitted values, “red”, “green” or “blue”, possibly ignoring the case, if CaseSensitive = False.

Validation = Wildcards, PatternString = “(412)*”: Input string must start with “(412)”, possibly ignoring the case, if CaseSensitive = False.

Validation = RegexPattern, PatternString = “[0-9]*”: Input string contains one or more digits.

Typed Value Validation (PostValidation) PostValidation allows you to validate the typed Value entered by the user.

You can check that the value matches one of the values in a pre-defined value list specified in the Values property.

You can also test the value to see if it is below a minimum or above a maximum, that is you can test to see if the value belongs to an interval. You can even specify multiple intervals of allowed values. The intervals are defined in the Intervals property where you specify minimum and maximum values for each interval, and also whether minimum and maximum values are used or ignored, and whether or not the inequality is strict (minimum/maximum value included).

You can also exclude some values using the ValuesExcluded property.

Finally, you can perform validation programmatically in the PostValidating event.


To distinguish between declarative and programmatic validation, use the Validation property with two possible values: ValuesAndIntervals and PostValidatingEvent. Note that PostValidatingEvent disables automatic validation of values and intervals. Call the ValidateValuesAndIntervals method from the event code if you want to combine event code with values and intervals validation.

Editing Date and Time Values C1TextBox supports a special editing mode called DateTimeInput mode that makes editing date and time values easier. This mode is enabled when DataType = DateTime and DateTimeInput = True (default). In the DateTimeInput mode, the currently selected date or time field, such as the year, month, date, etc, is highlighted and edited separately. Formatted fields represented in string form, such as month or day of the week in LongDate format, can be typed as numbers on the keyboard, and their string representation is updated automatically. Arrow Up/Down keys or mouse wheel can be used to increment/decrement the current field.

Additional properties controlling date-time input are:

MinShortYear The minimum year that can be entered without leading zeros (when DateTimeInput = True). For example, if MinShortYear = 300 (default), entering 200 is not allowed (will be ignored), whereas 400 is interpreted as 0400 A.D. Regardless of this property value, entering 0200 will be interpreted as year 0200 A.D.

CurrentTimeZone This property is True by default, which means that date-time values are invariant, not adjusted to time zones. If this property is set to False, the Text shown to the user and the underlying stored Value become different. The stored Value belongs to the time zone defined by the GMTOffset property specifying the offset in hours and minutes of the base time zone from Greenwich Mean Time. The Text shown to the user belongs to the local time zone defined by the user computer settings. Displaying values and parsing values entered by the user, C1Input adjusts it to the time zone difference.

To make editing date-time values even more convenient to the user, you can use the specialized C1DateEdit control. In addition to C1TextBox functionality, it supports a dropdown calendar and up-down buttons (speedbuttons) incrementing/decrementing the currently selected date-time field.

Editing Numeric Values C1TextBox supports a special editing mode called NumericInput mode that makes editing numeric values easier. This mode is enabled when NumericInput = True (default) and DataType is one of numeric data types (Byte, UInt16, UInt32, UInt64, SByte, Int16, Int32, Int64, Decimal, Single, Double). In the NumericInput mode, numbers are edited in a calculator-like fashion. It accepts only digits, +/- sign, and, if data type and format allow, decimal point and exponent. Other characters, such as letters, are ignored. There are also special functional keys recognized in NumericInput mode for values of type Single and Double: F9 (change sign), F2 (negative infinity), F3 (positive infinity), F4 (NaN, "not a number").

To make editing numbers even more convenient to the user, you can use the specialized C1NumericEdit control. In addition to C1TextBox functionality, it supports a dropdown calculator and up-down buttons (speedbuttons) incrementing/decrementing the value by the specified Increment.

Dropdown and Increment Buttons The specialized C1Input controls for date-time and numeric editing, C1DateEdit and C1NumericEdit controls support dropdown and increment/decrement (up/down) buttons. Button visibility is controlled by the ShowDropDownButton and ShowUpDownButtons properties.

To control dropdown alignment and distance from the control you can use the DropDownAlign and GapHeight properties. To open/close dropdown programmatically, use the OpenDropDown and CloseDropDown methods. Opening/closing dropdown triggers events DropDownOpened and DropDownClosed. You can use the DropDownOpened event to adjust dropdown properties (mostly,

Custom Dropdown · 31

calendar properties in C1DateEdit.Calendar) before the dropdown is shown to the user. You can check if the dropdown is open using the DroppedDown property.

C1DateEdit Control C1DateEdit control supports up/down buttons and dropdown calendar.

The Up/down buttons function if DateTimeInput = True. They increment/decrement the currently selected field of the date-time value, see Editing Date and Time Values (page 30.)

The dropdown calendar has the same object model as the standard MonthCalendar control (System.Windows.Forms.MonthCalendar) and almost the same appearance with additional buttons Clear, Today and two year navigation buttons. Button visibility is controlled by the properties ShowClearButton and ShowTodayButton. These properties and all other calendar properties are available both at design and at run time in the C1DateEdit.Calendar object. If you want to change calendar properties at run time when the calendar is opened, before it is shown to the user, use the DropDownOpened event.

C1NumericEdit Control C1NumericEdit control supports up/down buttons and dropdown calculator.

Up/down buttons increment/decrement the Value by the amount specified in the Increment property (default: 1).

The dropdown calculator follows the standard Windows calculator model, allows the user to perform calculations without leaving the control.

Custom Dropdown C1Input includes a powerful custom dropdown functionality that allows you to create any dropdown editor you need, in addition to the standard calendar and calculator dropdowns provided by C1Input. Dropdown editors are created visually as forms in your project.

To create your own custom dropdown editor, use the C1DropDownControl. This control class derives from C1TextBox and adds custom dropdown functionality and up-down buttons. To create a dropdown editor for your control, add a form to your project derived from C1.Win.C1Input.DropDownForm (see Tutorial 8) and select the form class name in the DropDownFormClassName property of your C1DropDownControl. In your DropDownForm-derived form you can set the Value property of C1DropDownControl when necessary (use the DropDownForm.OwnerControl property to get the control object), or you can do it when the form is closing, in the PostChanges event.

See the DropDownForm class reference for the full description of available options for custom dropdown forms. See also the Samples directory for common use samples of the custom dropdown functionality.

If you need to create a custom control with dropdown functionality, this can be done by deriving a custom control class from C1DropDownControl and overriding its DefaultDropDownFormClassName property.

Programmatic Formatting, Parsing and Validation If standard and custom format specifiers are not enough, you can format values in code in the Formatting event by setting the FormatType property to UseEvent, see Formatting Data (page 16. )In your formatting code, you can use the standard C1Input formatting as a helper or for any other purposes, calling the FormatInfo.Format method.

Parsing can also be done in event code, in the Parsing event, by setting the ParseInfo.FormatType property to UseEvent. You can use standard C1Input parsing routines in your code if you need them, with the following ParseInfo methods: Parse, ParseFixed, ParseFloat, ParseInteger, ParseBoolean, and ParseDateTime.


Some useful methods for edit mask management can be found in the MaskInfo class.

When you need to synchronize the Value property with the text currently entered by the user, call the UpdateValueWithCurrentText method. Normally, this synchronization is done automatically when the control loses focus, but in certain situations you may find necessary to call this method and force the Value update. Updating Value involves parsing the input text, validating, and updating the Value property, see Value and Text: Displaying, Validating and Updating Values (page 16. )You can also perform the first two phases, parsing and validation without changing the Value, using the methods ParseContent and CheckValidationResult.

Error Handling Error handling is very important in data input forms. C1Input gives developers full control over all kinds of error conditions:

Data Errors WinForms data sources such as ADO.NET and C1DataObjects contain provisions for detecting logical errors in data, by the data source itself or by the programmer, setting the RowError property or calling the SetColumnError method (SetFieldError in C1DataObjects). You can show logical row and column errors in C1Input using System.Windows.Form.ErrorProvider component.

To show logical column errors, use the ErrorProvider component with C1Input controls as you would use it with any other controls.

To show row error in C1DbNavigator control, set the C1DbNavigator.ErrorProvider property to an ErrorProvider component. Then C1DbNavigator will display error icon with RowError tooltip text when there is an error in current row.

Incorrect Format in Displaying Data It is possible, although generally avoided in applications, that data fetched from the database or another data source does not match the format or edit mask defined in a C1Input control. In such cases, the control cannot show its value properly formatted. Although C1Input controls have reasonable default behavior handling this situation, you may want to inform the user of invalid data. This is done using the ErrorInfo.ErrorProvider property (C1Label.ErrorProvider in C1Label control). If you set this property to an ErrorProvider component, C1Input uses that ErrorProvider component to signal errors when it displays invalid data (data that can’t be formatted for display in the control). It calls the ErrorProvider.SetControl method when such error is detected. Before doing that, C1Input fires the FormatError event where you can customize the error message (ErrorProvider tooltip text) and perform other actions.

User Input Errors When C1Input detects an error while parsing or validating input value, it fires the ValidationError event. Then, by default, it shows an error message. The default behavior can be changed and customized in different ways:

C1Input controls have an ErrorInfo property containing settings (properties of the ErrorInfo class) affecting error handling:

BeepOnError If True, the control beeps signaling an error. Default: False.

CanLoseFocus If True, the control is allowed to lose focus regardless of the error. This property is False by default, meaning that the control will stay in focus until the error is corrected. Note that setting ErrorAction to SetValueOnError or ResetValue allow the user to leave the control after error by resetting its value.

Error Handling · 33

ErrorAction Enumerated value that determines what action is performed on the control value when an error occurs. ErrorAction = None (default) means that Value is not changed, remains as it was before the unsuccessful value update. If ErrorAction = SetValueOnError, control’s Value is set to the value specified in the ValueOnError property of the ErrorInfo class. If ErrorAction = ResetValue, control’s Value is set to the last value the control had before it entered edit mode. Setting ErrorAction = ThrowException interrupts execution and throws an exception, ValidationException.

ErrorMessage Error message shown in the standard message box and/or in the exception.

ErrorMessageCaption The text to display in the title bar of the error message box.

ErrorProvider Gets or sets an ErrorProvider object used to indicate error state of the control.

ShowErrorMessage If True (default), the standard error message is shown.

ValueOnError Value used to reset the control if ErrorAction = SetValueOnError.

ValueOnErrorIsDbNull Boolean property used to set ValueOnError to DBNull (only necessary at design time).

In addition to that, ErrorMessage can be specified for particular actions: edit mask errors (MaskInfo.ErrorMessage), parsing (ParseInfo.ErrorMessage), pre- and post-validation (PreValidation.ErrorMessage, PostValidation.ErrorMessage). If a specialized error message is not specified in one of these sub-objects, the control’s ErrorInfo.ErrorMessage takes effect. Note that you can use ErrorProvider icon to indicate the error, instead of showing a message box, if you set ErrorInfo.ErrorProvider to an ErrorProvider component and ShowErrorMessage to False.

The properties listed above, when set in the control’s ErrorInfo object, affect all error handling in the control. When an error occurs, their values can be customized programmatically to handle that particular error. This is achieved by passing an ErrorInfo argument to the ValidationError event. The ErrorInfo argument passed to ValidationError is a copy of the control’s ErrorInfo with all its properties. It is an independent copy, so you can change properties in the ErrorInfo event argument for the current error without affecting the overall control’s ErrorInfo settings. By setting ErrorInfo properties in the ValidationError event you specify how to handle the error. For example, you can suppress the standard error message (and show your own message instead) by setting ShowErrorMessage = False, or you can change ValueOnError (and set ErrorAction = SetValueOnError), or change the ErrorMessage, etc. Keep in mind that you must set the properties of the ErrorInfo argument passed to the ValidationError event, not the properties of the control’s ErrorInfo.ErrorMessage.

After the ValidationError event, error handling proceeds as specified in the event’s ErrorInfo argument. If ErrorAction = ThrowException, an exception is thrown (using the ErrorMessage text). If BeepOnError = True, the control beeps. If ShowErrorMessage = True, the standard error message box is shown (with ErrorMessage text). After that, the control’s value may be changed if so specified by ErrorAction. Finally, moving focus to another control is either canceled or permitted, according to CanLoseFocus, if validation was triggered by an attempt to move focus out of the control. If ErrorInfo.ErrorProvider property is set to an


ErrorProvider component, that component is used to show the error icon near the offending control, with ErrorMessage tooltip (ErrorProvider.SetError is called).

If you perform parsing or validation programmatically, in event code, and exit the event with an error condition (set the event’s Succeeded argument to False), you can describe the error and how it must be handled by setting the properties of an ErrorInfo argument passed to the event. Such argument is provided for the following events: PreValidating, Parsing, PostValidating. Its initial values are taken from the control’s ErrorInfo property. This ErrorInfo argument that you change in the event is then passed to the ValidationError event where it can be further changed as described above.

Handling NULL and Empty Values NULL values (DBNull) can be difficult to handle without appropriate tools. C1Input provides flexible rules for handling nulls allowing the programmer the ability to solve this problem in practically any circumstance.

Displaying NULL and Empty Values When a control is not in edit mode or is read-only, null values are displayed according to the NullText property (which can be overridden in DisplayFormat.NullText). If the property EmptyAsNull is set to True (default: False), empty strings are also displayed with the same NullText string. The EmptyAsNull property can also be overridden in DisplayFormat.EmptyAsNull. In edit mode, the NullText and EmptyAsNull properties of the EditFormat object take effect, instead of those of DisplayFormat.

In edit mode with an active EditMask, the null value and the empty string are shown as an empty mask with literals in their places and prompt characters filling the rest.

When editing a date-time value with the DateTimeInput property set to True, the null value is represented by an empty control. When the user starts editing with a keystroke or mouse click, the control immediately turns to a non-null value, namely, to the last non-null value assigned to the control or to today’s date.

In programmatic formatting (FormatType = UseEvent), the Formatting event is only called for non-null values.

Entering NULL and Empty Values Unless in edit mask mode or in date-time editing with DateTimeInput = True, the user can enter a null value in one of the following ways:

• If the control text equals NullText, the resulting value is null. The effective NullText value here is determined by ParseInfo.NullText. Comparison with NullText is case-sensitive or not depending on the CaseSensitive property.

• Clearing the control, entering an empty string results in null value if the EmptyAsNull property is set to True (it is False by default).

• In programmatic parsing, DBNull value can be returned by the programmer in the Parsing event.

If the user enters a null value (either by entering an empty string or NullText, see above), input string validation and parsing are skipped, see Input string validation (PreValidation) (page 29 )and Parsing (Updating) Data (page 26. )However, PostValidation is performed in this case as in all others, see Typed value validation (PostValidation) (page 29.)

Visual Basic and C# Samples · 35

C1Input Samples Please be advised that this ComponentOne software title is accompanied by various sample projects and/or demos, which may or not make use of other ComponentOne development tools. While the sample projects and/or demos included with the software are used to demonstrate and highlight the product’s features, and how the control may be integrated with the rest of the ComponentOne product line, some of the controls used in the demo/sample project may not be included with the purchase of certain individual products.

Visual Basic and C# Samples

CreditCardDropDown Using a custom dropdown form. This sample uses the C1DropDownControl and DropDownForm controls.

FormattingInBinding

Demonstrates the use of two important events of C1TextBox, C1Label, and C1PictureBox controls.This sample uses the C1DateEdit, C1DbNavigator, C1Label, and C1PictureBox controls.

InheritedDropDown

Implements a fully functional font editing control based onC1DropDrownControl. The user can change font properties with the texteditor or open the dropdown portion to change font properties in a more convenient way. This sample uses the C1DropDownControl, C1TextBox, and DropDownForm controls.

NumPadDropDown1 Replaces the standard calculator in a C1NumericEdit control with the custom dropdown numpad. This sample uses the C1NumericEdit and DropDownForm controls.

NumPadDropDown2 Demonstrates the ability to enter numbers with the mouse or other pointing device.This sample uses the C1DbNavigator, C1NumericEdit, and DropDownForm controls.

Tutorial 1 – Binding C1Input Controls to a Data Source · 37

C1Input Tutorials Note: If you are running the pre-built tutorial projects included in C1Input installation, please be aware that the projects have the sample database location hard coded in the connection string:

C:\Program Files\ComponentOne Studio.NET\Common\NWIND.MDB

If you have the Northwind database installed in a different location, you can change the connection string, or copy the NWIND.MDB file to the required location.

Tutorial 1 – Binding C1Input Controls to a Data Source In this tutorial, you will see how easy it is to show database data in a form using C1Input components. Without any manual coding, you can format data, navigate data source rows, even display pictures.

C1Input controls support data binding to any .NET data source objects. Among them, you can use any standard ADO.NET object, such as DataTable, DataView or DataSet as your data source. The alternative and recommended way is to use ComponentOne C1DataObjects framework, a part of ComponentOne Studio for .NET adding many enhancements to ADO.NET. We will use C1DataObjects Express Edition (C1DataExpress) data source in all our tutorials except this first one, since it is the easiest way to bind to data in a .NET application. If you are interested in ADO.NET versions of tutorial projects, they can be found in the Tutorials\ADO.NET subdirectory. This tutorial will show how to bind both to C1DataObjects and to ADO.NET.

Binding to a C1DataExpress Data Source 1. Create a new Windows Application project. Make sure the C1Input and C1DataExpress components

are added to your Visual Studio toolbox as described in the installation instructions.

2. Place the following components on the form as shown in the figure: C1ExpressTable1 (C1.Data.Express.C1ExpressTable), C1Label1-3 (C1.Win.C1Input.C1Label), C1PictureBox1 (C1.Win.C1Input.C1PictureBox), C1TextBox1 (C1.Win.C1Input.C1TextBox), C1DbNavigator1 (C1.Win.C1Input.C1DbNavigator):

38 · C1Input Tutorials

3. Select the C1ExpressTable1 component, go to the Properties window, open the ConnectionString property combo box and select <New Connection…>. It will open the standard OLE DB Data Link Properties dialog. Select the provider, the database and other necessary connection properties in that dialog. In these tutorials, we use the standard MS Access Northwind sample database (NWIND.MDB). Select “Microsoft Jet 4.0 OLE DB Provider” in the Provider tab, and “C:\Program Files\ComponentOne Studio.NET\Common\NWIND.MDB” (or another location, where your database is) in the Connection tab. Press OK. That will close the Data Link Properties dialog and put the connection string in the ConnectionString property.

4. For the C1ExpressTable1 component, open the DbTableName property combo box and select Employees from the database table list.

5. Now, we will bind some C1Input controls to the data control. Suppose we want to show the first name, date of birth, notes and photo for each employee. The first name and date of birth will be displayed in C1Label controls, notes in C1TextBox, and photo in C1PictureBox. For the C1Label1 control, go to the Properties window, select "C1ExpressTable1" from the dropdown list for the DataSource property, and then select "FirstName" from the list for the DataField property:

C1Label1.DataSource = C1ExpressTable1 C1Label1.DataField = FirstName

6. As in step 5, bind C1Label2 to “C1ExpressTable1 - BirthDate” and C1TextBox1 to “C1ExpressTable1 - Notes”:

C1Label2.DataSource = C1ExpressTable1 C1Label2.DataField = BirthDate CTextBox1.DataSource = C1ExpressTable1 CTextBox1.DataField = Notes

7. After binding the C1Label2 control, you can notice that its DataType property is set to the field type, DateTime. Now, change the format for C1Label2 so that it will not show time with the date of birth


(showing time is the default). To change the format, select the FormatType property, open its combo box and select “Medium Date”.

8. Bind the C1PictureBox control to the Photo field. First select C1ExpressTable in the DataSource property combo box of the C1PictureBox control, then open the DataField property combo box and select Photo from the list of available fields:

C1PictureBox1.DataSource = C1ExpressTable1 C1PictureBox1.DataField = Photo

9. C1PictureBox1.DataField := 'Photo';Set up the C1DbNavigator1 control allowing the user to navigate through the data set. To bind the navigator control to the data source, select C1ExpressTable1 in its DataSource property combo box.

C1DbNavigator1.DataSource = C1ExpressTable1

10. To dock the navigator control to the bottom of the form and separate it from the rest of the form with a 3d line, set the following properties:

C1DbNavigator1.Dock = Bottom C1Label3.Dock = Bottom C1Label3.BorderStyle = Fixed3D

Run the Program and Observe the Following:

C1Input controls show data in Employees records. You can navigate between Employees records using the four VCR-style buttons of the navigator control. You can also go directly to a certain record by typing the record number in the navigator control record number edit field, or set the input focus to the record number field and use mouse wheel to scroll through the records.


Binding to an ADO.NET Data Source 1. Create a new Windows Application project. Make sure the C1Input components are added to your

Visual Studio toolbox as described in the installation instructions.

2. Place the following components on the form as shown in the figure: C1Label1-3 (C1.Win.C1Input.C1Label), C1PictureBox1 (C1.Win.C1Input.C1PictureBox), C1TextBox1 (C1.Win.C1Input.C1TextBox), C1DbNavigator1 (C1.Win.C1Input.C1DbNavigator):

3. Place an OleDbDataAdapter component (located on the Data tab of the Toolbox) on the form. This will start Data Adapter Configuration Wizard. In the wizard, select or create a connection to the Nwind sample database and build a query retrieving all fields from the table Employees.

4. Generate a data set for the adapter created in the previous step. Select Generate Dataset either from the form context menu or from the Data menu, then select the New radio button in the Generate Dataset dialog and press OK. This will create a dataSet11 component on the form.

5. Double-click the form and enter the following code in the Form_Load event handler:

• Visual Basic

OleDbDataAdapter1.Fill(DataSet11)

• C#

oleDbDataAdapter1.Fill(dataSet11);

• Delphi

OleDbDataAdapter1.Fill(DataSet11);

6. Now, we will bind C1Input controls to the data source. Suppose we want to show the first name, date of birth, notes and photo for each employee. The first name and date of birth will be displayed in a


C1Label control, notes in C1TextBox, and photo in C1PictureBox. For the C1Label1 control, go to the Properties window, select "dataSet11" from the dropdown list for the DataSource property, and then select "Employees.FirstName" from the list for the DataField property:

C1Label1.DataSource = dataSet11 C1Label1.DataField = Employees.FirstName

7. As in step 6, bind C1Label2 to “dataSet11 - Employees.BirthDate” and C1TextBox to “dataSet11 - Employees.Notes”:

C1Label2.DataSource = dataSet11 C1Label2.DataField = Employees.BirthDate CTextBox1.DataSource = dataSet11 CTextBox1.DataField = Employees.Notes

8. After binding the C1Label2 control, you can notice that its DataType property is set to the field type, DateTime. Now, change the format for C1Label2 so that it will not show time with the date of birth (showing time is the default). To change the format, select the FormatType property, open its combo box and select “Medium Date”.

9. Bind the C1PictureBox control to the Photo field. First select dataSet11 in the DataSource property combo box of the C1PictureBox control, then open the DataField property combo box and select Employees.Photo from the list of available fields:

C1PictureBox1.DataSource = dataSet11 C1PictureBox1.DataField = Employees.Photo

10. Set up the C1DbNavigator1 control allowing the user to navigate through the data set. To bind the navigator control to the data source, first select dataSet11 in its DataSource property combo box, then select Employees in its DataMember property combo box:

C1DbNavigator1.DataSource = dataSet11 C1DbNavigator1.DataMember = Employees

11. To dock the navigator control to the bottom of the form and separate it from the rest of the form with a 3d line, set the following properties:

C1DbNavigator1.Dock = Bottom C1Label3.Dock = Bottom C1Label3.BorderStyle = Fixed3D


C1Input controls show data in Employees records. You can navigate between Employees records using the four VCR-style buttons of the navigator control. You can also go directly to a certain record by typing the record number in the navigator control record number edit field, or set the input focus to the record number field and use mouse wheel to scroll through the records.


Tutorial 2 – Masked Input In this tutorial, you will learn how to use edit mask to facilitate and restrict user input.

1. Create a new Windows Application project. Place the following components on the form as shown in the figure: c1ExpressConnection1 (C1.Data.Express.C1ExpressConnection), c1ExpressTable1-3 (C1.Data.Express.C1ExpressTable), Label1-7, labStoredExpNumber, labStoredDateTime, labStoredPhone, labStoredMultiline (all of type System.Windows.Forms.Label), c1TextBox1-7 (C1.Win.C1Input .C1TextBox), labCompanyName, labCustomerID, labOrderDate, labFreight (C1.Win.Input.C1Label), c1DbNavigator1 (C1.Win.C1Input .C1DbNavigator), btnClose (System.Windows.Forms.Button).

Tutorial 2 – Masked Input · 43

2. Select the c1ExpressConnection1 component, go to the Properties window, open the ConnectionString property combo box and select <New Connection…>. It will open the standard OLE DB Data Link Properties dialog. Select the provider, the database and other necessary connection properties in that dialog. In these tutorials, we use the standard MS Access Northwind sample database (NWIND.MDB). Select “Microsoft Jet 4.0 OLE DB Provider” in the Provider tab, and “C:\Program Files\ComponentOne Studio.NET\Common\NWIND.MDB” (or another location, where your database is) in the Connection tab. Press OK to close the Data Link Properties dialog and put the connection string in the ConnectionString property.

3. Set the properties of c1ExpressTable1-3 as follows:

c1ExpressTable1.ConnectionComponent = c1ExpressConnection1 c1ExpressTable1.DbTableName = Customers c1ExpressTable2.ConnectionComponent = c1ExpressConnection1 c1ExpressTable2.DbTableName = Orders c1ExpressTable3.ConnectionComponent = c1ExpressConnection1 c1ExpressTable3.DbTableName = <Composite…>

In the Composite Table Editor add Customers table and then Orders table related as One-to-Many. Add Customers.CustomerID – Orders.CustomerID join for the Orders table.

4. To bind controls to the data source, set properties:

c1DbNavigator1.DataSource = c1ExpressConnection1 c1DbNavigator1.DataMember = CompositeTable labCompanyName.DataSource = c1ExpressConnection1 labCompanyName.DataField = CompositeTable.CompanyName labCustomerID.DataSource = c1ExpressConnection1 labCustomerID.DataField = CompositeTable.CustomerID labOrderDate.DataSource = c1ExpressConnection1 labOrderDate.DataField = CompositeTable.OrderDate labFreight.DataSource = c1ExpressConnection1 labFreight.DataField = CompositeTable.Freight c1TextBox6.DataSource = c1ExpressConnection1 c1TextBox6.DataField = CompositeTable.CustomerID c1TextBox7.DataSource = c1ExpressConnection1 c1TextBox7.DataField = CompositeTable.OrderDate c1TextBox8.DataSource = c1ExpressConnection1 c1TextBox8.DataField = CompositeTable.Freight

5. Labels labStoredXXX located to the right of c1TextBox1-4 controls display the current Value property of the corresponding C1TextBox. To synchronize them with c1TextBox1-4, create event handlers c1TextBox1(…4)_ValueChanged. For example, this is the handler for c1TextBox1:

• Visual Basic

Private Sub c1TextBox1_ValueChanged( ByVal sender As Object, ByVal e As System.EventArgs) Handles c1TextBox1.ValueChanged Try labStoredExpNumber.Text = CType(c1TextBox1.Value, String) Catch labStoredExpNumber.Text = "" End Try End Sub

• C# private void c1TextBox1_ValueChanged(object sender, System.EventArgs e) { try { labStoredExpNumber.Text =


(string)c1TextBox1.Value; } catch { labStoredExpNumber.Text = ""; } }

• Delphi

procedure TWinForm.c1TextBox1_ValueChanged(sender: System.Object; e: System.EventArgs); begin try labStoredExpNumber.Text := String(c1TextBox1.Value); except labStoredExpNumber.Text := ''; end; end;

6. c1TextBox1 allows to enter numbers with or without fractional part and with optional exponent. It uses the WhenNextStarted mode of showing mask literals, so the decimal point appears only when necessary, when the user starts entering the decimal part. Set the EditMask property of c1TextBox1 to !###0.^999e#9. Here '#' is an optional position for a digit or sign, '9' is an optional position for a digit, '0' is a required position for a digit, '!' is a special character specifying right justification for the following text, '^' cancels right justification mode, 'e' – a literal. Then expand the c1TextBox1.MaskInfo property and set ShowLiterals to WhenNextStarted.

Note: C1TextBox and C1NumericEdit support a special edit mode, NumericInput mode facilitating input of any numeric data type. It is usually more convenient for numeric input than edit mask. Try NumericInput before using an edit mask for numeric data.

c1TextBox2 is used for entering a date/time value. Set the c1TextBox2.EditMask property to !90/90/9900 90:90 >PM. There are two new special characters used in this mask: '>' causes the next characters to be converted to upper case, 'P' is a non-standard special character (custom placeholder) allowing entering either 'A' or 'P'. To define a custom placeholder, expand the property c1TextBox2.MaskInfo and press the button in the CustomPlaceholders property to open the Collection Editor. In the Collection Editor, add a new item. Set the properties of the newly added item:

Placeholder = P LookupChars = AP

Thus the letter 'P' represents a position in edit mask where the user can type 'A' or 'P'.

Now, we want to specify that entered date/time values are stored in the database in a compact form without literals. For example, the value "11/_8/2002 _1:42 PM" is stored as "11*82002*142P". To enable this storage format, set SaveBlanks to True and SaveLiterals to False (both properties are contained in c1TextBox2.MaskInfo). Also, change StoredEmptyChar from default '_' to '*' to store asterisk in blank positions. If you set SaveBlanks = False, SaveLiterals = True, blank positions will not be saved in the database, the above data will be saved as “11/8/2002 1:42PM”.

Note: C1TextBox and C1DateEdit support a special edit mode, DateTimeInput mode facilitating input of date/time data. It is usually more convenient for date/time input than edit mask. Try DateTimeInput before using an edit mask for date/time data.

Set up the c1TextBox3 control for telephone number input with mask (999) 0099-00099. Here ‘9’ is an optional digit position, ‘0’ is a required digit position. Set the EditMask property of the c1TextBox3 control to (999) 0099-00099, then expand the MaskInfo property and set AutoTabWhenFilled to

Tutorial 3 – Data Navigation and Actions Using C1DbNavigator · 45

True. This will automatically move the input focus to the next control once the user fills the last mask position.

The c1TextBox4 control demonstrates multiline mask input. Set its Multiline property to True, ScrollBars to Vertical and EditMask property to

"First Name: "CCCCCCCCCCCCCCC\n"Last Name: "CCCCCCCCCCCCCCCCCCCC\n"Date of Birth: "!90/90/9900^\n"Work Status: "CCCCCCCCCCCCCCC\n"Salary: $"!######0.^99

Here ‘\n’ represents a line break. Now expand the MaskInfo property and set MaskInfo.SaveBlanks to True. This ensures that all positions left blank by the user are saved as spaces. If SaveBlanks = False, optional positions not filled by the user will be ignored. Additionally, you can set MaskInfo.SaveLiterals to False, that will prevent saving literal texts, so only the information typed by the user is saved.

All the previous controls were unbound. Let us also configure some data bound C1Label and C1TextBox controls. They are located at the bottom of the form. Their data binding properties were set on Step 4. Set their other properties as follows:

labCustomerID.MaskInfo.EditMask = >LLLLL c1TextBox6.EditMask = >LLLLL labOrderDate.FormatType = CustomFormat labOrderDate.CustomFormat = M/d/yyyy labOrderDate.MaskInfo.EditMask = !90/90/0000 c1TextBox6.FormatType = CustomFormat c1TextBox6.CustomFormat = M/d/yyyy c1TextBox6.MaskInfo.EditMask = !90/90/0000 labFreight.FormatType = CustomFormat labFreight.CustomFormat = $ ####0.## labFreight.MaskInfo.EditMask = $ !99990.^99 c1TextBox7.FormatType = CustomFormat c1TextBox7.CustomFormat = $ ####0.## c1TextBox7.EditMask = $ !99990.^99


• Mask characters appear when you move focus to a control (except c1TextBox1 that has ShowLiterals set to WhenNextStarted).

• In edit mode, empty mask positions are shown using PromptChar (default: ‘_’). When the control loses focus, these positions are hidden.

• Experiment typing in the controls and look at the stored values displayed in the labels.

• If you select the whole text and press Delete, the input control is cleared. Depending on the MaskInfo.EmptyAsNull, this is interpreted either as DBNull value or as current edit cancellation, reverting to the previous value when the control loses focus. The same effect, canceling edit, has the Esc key.

Tutorial 3 – Data Navigation and Actions Using C1DbNavigator This tutorial demonstrates the main features of the C1DbNavigator control. Its primary goal is to navigate through data source rows, but it can also be used to perform common actions on data such as adding rows, confirming changes, updating the data source, refresh from the data source (canceling changes), and others.

1. Create a new Windows Application project.

2. Place the following components on the form as shown in the figure: C1ExpressConnection (C1.Data.Express.C1ExpressConnection), C1ExpressTable1-2 (C1.Data.Express.C1ExpressTable),


C1Label1-3 (C1.Win.C1Input.C1Label), dataGrid (System.Windows.Forms.DataGrid), C1DbNavigator1-3 (C1.Win.C1Input.C1DbNavigator), btnClose (System.Windows.Forms.Button). Note: For all label controls, set the TextDetached property to True. This is necessary to set their Text property.

3. Select the C1ExpressConnection1 component, go to the Properties window, open the ConnectionString property combo box and select <New Connection…>. It will open the standard OLE DB Data Link Properties dialog. Select the provider, the database and other necessary connection properties in that dialog. In these tutorials, we use the standard MS Access Northwind sample database (NWIND.MDB). Select “Microsoft Jet 4.0 OLE DB Provider” in the Provider tab, and “C:\Program Files\ComponentOne Studio.NET\Common\NWIND.MDB” (or another location, where your database is) in the Connection tab. Press OK. That will close the Data Link Properties dialog and put the connection string in the ConnectionString property.

4. Set the properties of C1ExpressTable1-2 as follows:

C1ExpressTable1.ConnectionComponent = C1ExpressConnection1 C1ExpressTable1.DbTableName = Customers C1ExpressTable2.ConnectionComponent = C1ExpressConnection1 C1ExpressTable2.DbTableName = Orders

5. Also, you need to set the AutoIncrement property of one of the fields of C1ExpressTable2, otherwise you will not be able to update data in the database: Select C1ExpressTable2, press the ellipsis button in the properties window for the Fields property to open the Fields dialog box, select the OrderID field and set its AutoIncrement property to ClientAndServer. This is necessary because OrderID is an autoincrement field in the database, so it must be treated accordingly by C1DataExpress.

Tutorial 3 – Data Navigation and Actions Using C1DbNavigator · 47

6. Create a master-detail relation between C1ExpressTable1 (master) and C1ExpressTable2 (detail). Press the ellipsis button in the Relations property of the C1ExpressionConnection1 control to open the Relations dialog. In the dialog, select “Customers” for Parent, “Orders” for Child, add a join with CustomerID for both Parent field and Child field, press OK to close the Relations dialog.


dataGrid1.DataSource = C1ExpressConnection1 dataGrid1.DataMember = _Customers C1DbNavigator1.DataSource = C1ExpressConnection1 C1DbNavigator1.DataMember = _Customers dataGrid2.DataSource = C1ExpressConnection1 dataGrid2.DataMember = _Customers.Customers – Orders C1DbNavigator2.DataSource = C1ExpressConnection1 C1DbNavigator2.DataMember = _Customers.Customers – Orders

8. Now C1DbNavigator1 allows us to navigate the master table Customers, and C1DbNavigator1 – the detail table Orders. However, we want some more functionality for our navigator control. we want the user to be able to perform common data action pressing navigator buttons. Using the VisibleButtons property, show the following buttons for C1DbNavigator1-2: Add, Delete, Apply, Cancel. By default, a navigator control also shows the current row number and row count. To save space, hide this information be setting the PositionVisible property to False.

9. The third navigator control, C1DbNavigator3 is used to perform update and refresh for the whole data set (both tables Customers and Orders). To hide redundant navigator fields and buttons, set PositionVisible to False and select only two buttons, Update and Refresh in the VisibleButtons property. Update and refresh buttons do not have built-in functionality, since their function may be different with different data sources. To make them work, you need to write code in event handlers. Create the following event handlers:

• Visual Basic

Private Sub C1DbNavigator3_UpdateData(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles C1DbNavigator3.UpdateData C1ExpressConnection1.Update() End Sub Private Sub C1DbNavigator3_RefreshData(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles C1DbNavigator3.RefreshData C1ExpressConnection1.Fill() End Sub

• C#

private void C1DbNavigator3_UpdateData(object sender, System.EventArgs e) { C1ExpressConnection1.Update(); } private void C1DbNavigator3_RefreshData(object sender, System.EventArgs e) { C1ExpressConnection1.Fill(); }

• Delphi

procedure TWinForm1.C1DbNavigator3_UpdateData(sender: System.Object; e: System.EventArgs); begin C1ExpressConnection1.Update; end;


procedure TWinForm1.C1DbNavigator3_RefreshData(sender: System.Object; e: System.EventArgs); begin C1ExpressConnection1.Fill; end;

10. Navigator buttons can be monochrome, color (ColorButtons = True) or changing their color when hovered over (ColorWhenHover = True). They can also be 3d (standard) or flat depending on the ButtonStyle property. Set the following properties:

C1DbNavigator1.ButtonStyle = Standard C1DbNavigator1.ColorButtons = True

Using properties UIStrings and ButtonToolTips, it is also possible to change the texts displayed in the navigator and to change button tooltips. For instance, we could specify the first button tooltip as “Select the first customer” instead of the default “First record”. These properties can also be used to localize your application.


• By pressing the navigator buttons, you can move through the rows. If you press the Next button and hold it for a certain time (determined by the MoveDelayFirst property), the current position will change automatically with frequency determined by the MoveDelayNext property.

• You can jump to any row number by typing the number in the navigator position area in C1DbNavigator1. You can also use arrow keys and mouse wheel in that area to move to next or previous rows. Home and End keys move to the first and last row. PageUp/PageDown keys or mouse wheel with Ctrl key pressed page throw the rowset.

• If you change the value in a grid cell and press Cancel, the modified value will revert to the original value.

• You can add new rows with the Add button and delete rows with the Delete button.

• You can send changes to the database with Update button and re-fetch data from the database (discarding the changes you may have made) with the Refresh button.

Tutorial 4 – Using C1TextBox for Date-Time Input When editing date-time data with the property DateTimeInput set to True, the C1TextBox and C1DateEdit controls work in a special mode. In this mode, instead of editing date-time values as regular strings, they are divided into separate fields for month, day, hour, etc. It looks similar to the standard DateTimePicker control. However, C1TextBox and C1DateEdit support more formats than the standard DateTimePicker control and have many additional features, such as time zone adjustment, culture-dependent date formatting, etc.

1. Create a new Windows Application project. Place the following components on the form as shown in the figure: C1ExpressTable1 (C1.Data.Express.C1ExpressTable), C1Label1-9 (C1.Win.C1Input.C1Label), C1TextBox1-5 (C1.Win.C1Input.C1TextBox), C1DbNavigator1 (C1.Win.C1Input.C1DbNavigator), btnClose (System.Windows.Forms.Button). Note: For all label controls, set the TextDetached property to True. This is necessary to set their Text property.

Tutorial 4 – Using C1TextBox for Date-Time Input · 49

2. Repeating step 3 of Tutorial 1 set up the C1ExpressTable1 control with ConnectionString pointing to the sample database.

3. For the C1ExpressTable1 component, open the DbTableName property combo box and select Orders from the database table list. Also, you need to set the AutoIncrement property of one of the fields of C1ExpressTable1, otherwise you will not be able to update data in the database: Select C1ExpressTable1, press the ellipsis button in the Properties window for the Fields property to open the Fields dialog box, select the OrderID field and set its AutoIncrement property to ClientAnd Server. This is necessary because OrderID is an autoincrement field in the database, so it must be treated accordingly by C1DataExpress.

4. Bind controls to the data source:

C1DbNavigator1.DataSource = C1ExpressTable1 C1Label1.DataSource = C1ExpressTable1 C1Label1.DataField = OrderID C1TextBox1.DataSource = C1ExpressTable1 C1TextBox1.DataField = OrderDate C1TextBox2.DataSource = C1ExpressTable1 C1TextBox2.DataField = RequiredDate C1TextBox3.DataSource = C1ExpressTable1 C1TextBox3.DataField = ShippedDate C1Label8.DataSource = C1ExpressTable1 C1Label8.DataField = ShippedDate

5. Set up the navigator control C1DbNavigator1. Set its PositionVisible property to False and ColorButtons property to True. Expanding the VisibleButtons property, set the following flags to True: First, Previous, Next, Last, Apply, Cancel, Update, Refresh. Create the following event handlers (see Tutorial 3 for details):

• Visual Basic

Private Sub C1DbNavigator1_RefreshData(ByVal sender As Object, ByVal e As System.EventArgs) Handles C1DbNavigator1.RefreshData C1ExpressTable1.ExpressConnection.Fill() End Sub


Private Sub C1DbNavigator1_UpdateData(ByVal sender As Object, ByVal e As System.EventArgs) Handles C1DbNavigator1.UpdateData C1ExpressTable1.ExpressConnection.Update() End Sub

• C#

private void C1DbNavigator1_RefreshData(object sender, System.EventArgs e)

{

C1ExpressTable1.ExpressConnection.Fill();

}

private void C1DbNavigator1_UpdateData(object sender, System.EventArgs e)

{

C1ExpressTable1.ExpressConnection.Update();

}

• Delphi

procedure TWinForm1.C1DbNavigator3_UpdateData(sender: System.Object; e: System.EventArgs);

begin

C1ExpressConnection1.Update;

end;

procedure TWinForm1.C1DbNavigator3_RefreshData(sender: System.Object; e: System.EventArgs);

begin

C1ExpressConnection1.Fill;

end;

6. In C1TextBox1, we will represent the OrderDate in a full format, with full day of week, day, full month name and year. To specify that, just select

C1TextBox1.FormatType = LongDate

Since we leave the DateTimeInput property with its default value True, we will get date-time editing with separate fields for day of week, month, day and year at run time. In the C1TextBox2 control we use the ShortDate format:

C1TextBox2.FormatType = ShortDate

LongDate and ShortDate are examples of standard .NET formats. Their actual representation depends on the regional settings controlled by the Culture property.

7. The C1TextBox3 control demonstrates how you can represent a date in different formats depending on whether it is in edit or display mode (whether it has the input focus). We will make it LongDateShortTime when the control does not have input focus, and in edit mode, when it has input focus, we will use custom format with time zone. To begin with the custom format:

C1TextBox3.FormatType = CustomFormat C1textBox3.CustomFormat = MM/dd/yyyy h:mm tt zzz

Tutorial 4 – Using C1TextBox for Date-Time Input · 51

This format is the control’s default format (where tt is the AM/PM designator and zzz is the time zone representation). We can override it, and other format-related properties, for display and/or edit mode using properties DisplayFormat and EditFormat. Expand the DisplayFormat property, then expand its sub-property (Inherit) and select False for the FormatType flag. That will break the inheritance from control for the DisplayFormat.FormatType property and allow us to change it. Set this property, and also set the FormatType property for C1Label8 at this time:

C1TextBox3.DisplayFormat.FormatType = LongDateShortTime C1Lable8.FormatType = LongDateShortTime

8. Specify how NULL values (DBNull) are displayed in C1TextBox3 and in C1Label8. Set properties

C1TextBox3.NullText = (not shipped yet) C1Lable8.NullText = (null) C1TextBox3.EmptyAsNull = True

By default, clearing the control (select all and press Delete) reverts it to the value it had before editing once the control loses focus. We changed this behavior setting the EmptyAsNull property to True, now clearing the control sets its value to DBNull.

9. The C1TextBox3 control also demonstrates the time zone adjustment feature. It is useful in situations where information is entered into the database by operators located in different time zones. Then it is convenient to show and edit dates for each operator in his or her local time, but store the entered dates in the database adjusted to a single, unified time zone. Suppose the database server is located in Mountain Time zone (7 hours to the West from GMT, Greenwich Mean Time). To enable time zone adjustment, set the control’s CurrentTimeZone property to False. This will make the GMTOffset property modifiable. Set the GMTOffset property to –07:00 (Mountain Standard Time). Now C1TextBox3 converts all values to the local time before displaying them, and vice versa, converts values entered by the user to the Mountain Time zone.

10. The next control, C1TextBox4 demonstrates how date input can be localized for any culture supported in .NET. Set the Culture property to “Thai (Thailand)” and FormatType to LongDate. Then date format, including month names and year number, will be defined by the Thai Buddhist calendar.

11. The last control, C1TextBox5 allows to enter precise time with milliseconds. Set the FormatType property to CustomFormat and the CustomFormat property to “HH:mm:ss.fff”. Since this control is not data bound, to start editing from a non-empty value, set the Value property to some date-time value.


• Due to the setting DateTimeInput = True, you can edit date-time fields, such as year, month, day separately. You can type on the keyboard (months are entered numerically even if month name is shown) or use arrow keys or mouse wheel to advance a field. The AM/PM designator can be changed typing the first letter.

• When the C1TextBox3 control takes focus, the date format in it changes. You can specify the time zone in which the date is entered. By default, it is your local time zone. When you enter a date in C1TextBox3 and move focus away from the control, the C1Label8 control below shows the actual value stored in the database (and in the control’s Value property). It is adjusted to the Mountain Time zone.


Tutorial 5 – Data Validation The main feature of C1TextBox that distinguishes it from the standard TextBox control is that it works with typed data. When the user enters something in a C1TextBox control (or its descendant, C1DateEdit or C1NumericEdit), the input string undergoes several transition phases before it becomes a typed value of the Value property. The first phase is edit mask parsing (if an edit mask is active, see tutorial 2), extracting the stored content string out of the masked string displayed in the control. The next phase is PreValidation of the input string. This validation is always performed over a string value, regardless of the DataType, since at this time the input string is not yet converted to a typed value (not yet parsed). The next phase after pre-validation is parsing, that is, conversion to the required data type specified in the DataType property. The last phase before modifying the Value property is PostValidation that is performed over the typed value obtained by parsing. If the value satisfies the PostValidation conditions, it is assigned to the Value property. Of course, all these phases are optional, except parsing (and that is optional too, if DataType = String), they only occur if you specify validation conditions in corresponding properties.

This tutorial demonstrates pre-validation and post-validation, that is, how you can perform validation logic before and after parsing the input string.

1. Create a new Windows Application project. Place the following components on the form as shown in the figure: C1ExpressConnection (C1.Data.Express.C1ExpressConnection), C1ExpressTable1-2 (C1.Data.Express.C1ExpressTable), C1Label1-9 (C1.Win.C1Input.C1Label), C1TextBox1-5, C1DbNavigator1-2 (C1.Win.C1Input.C1DbNavigator), btnClose (System.Windows.Forms.Button). Note: For all label controls except C1Label7, set the TextDetached property to True. This is necessary to set their Text property.

2. Select the C1ExpressConnection1 component, go to the Properties window, open the ConnectionString property combo box and select <New Connection…>. It will open the standard OLE DB Data Link Properties dialog. Select the provider, the database and other necessary connection properties in that dialog. In these tutorials, we use the standard MS Access Northwind sample database (NWIND.MDB). Select “Microsoft Jet 4.0 OLE DB Provider” in the Provider tab,

Tutorial 5 – Data Validation · 53

and “C:\Program Files\ComponentOne Studio.NET\Common\NWIND.MDB” (or another location, where your database is) in the Connection tab. Press OK. That will close the Data Link Properties dialog and put the connection string in the ConnectionString property.


C1ExpressTable1.ConnectionComponent = C1ExpressConnection1 C1ExpressTable1.DbTableName = Customers C1ExpressTable2.ConnectionComponent = C1ExpressConnection1 C1ExpressTable2.DbTableName = Products


C1DbNavigator1.DataSource = C1ExpressTable1 C1DbNavigator2.DataSource = C1ExpressTable2 C1Label7.DataSource = C1ExpressTable1 C1Label7.DataField = _CompanyName C1TextBox1.DataSource = C1ExpressTable1 C1TextBox1.DataField = Country C1TextBox2.DataSource = C1ExpressTable1 C1TextBox2.DataField = Phone C1TextBox3.DataSource = C1ExpressTable1 C1TextBox3.DataField = Fax C1TextBox4.DataSource = C1ExpressTable2 C1TextBox4.DataField = UnitPrice C1TextBox5.DataSource = C1ExpressTable2 C1TextBox5.DataField = UnitsInStock

5. Set up the navigator controls. For both C1DbNavigator1 and C1DbNavigator2 set the PositionVisible property to False. In C1DbNavigator1 show two additional buttons using the VisibleButtons property: Cancel and Apply.

6. The top part of the form contains controls demonstrating pre-validation, the bottom part demonstrates post-validation. The first editable control, C1TextBox1 allows to enter a country name from a list of allowed countries. Expand the PreValidation property of that control and set its PatternString sub-property to "Canada, France, Germany, UK, USA". The separator string dividing the list to separate items is specified in the ItemSeparator property. Although we could use the default “|”, we set ItemSeparator to “, “ (comma and space) for better readability. The fact that PatternString represents an exact list of values to match the input string against is indicated by the value of the PostValidation.Validation property set to ExactList. This is default, so we do not have to change it.

7. The next control, C1TextBox2 validates user input using wildcard patterns. The input string is a telephone number. Different countries have different conventional phone numbers formats. We allow input strings in either of the three formats, for US, France and Germany. In this case, the PatternString contains three items, each item a wildcard pattern. An input string satisfies the condition if it matches one of the patterns. Expand the PreValidation property and set its sub-properties:

PreValidation.Valiation = Wildcards PreValidation.PatternString = (*) ###-####|##.##.##.##|####-######

8. Wildcard pattern validation demonstrated in the previous step is often not accurate enough. For instance, you cannot enter three digits instead of four in the third pattern. This kind of validation is better performed with regular expressions. .NET regular expressions is a very powerful means of string validation. The C1TextBox3 control contains a fax number and string validation is specified with the following property settings:

PreValidation.Validation = RegexPattern PreValidation.PatternString = ($\d+$ )?(\d+-\d+|(\d\d.){3}\d\d)

9. The C1TextBox4 control validates the typed Value for the UnitPrice field (post-validation). The validation condition is that the price must be between 0 and 10,000 (0 and 10,000 included), and the price of $12.00 is not allowed. To specify such constraints, expand the PostValidation property and


press the ellipsis button of the Intervals sub-property to open the Intervals Collection Editor dialog. In this dialog, you can specify one or more intervals. The input value must belong to one of them. Add an interval and set its MinValue to 0 and MaxValue to 10000. Press OK to close the dialog. Now specify the excluded value, 12.00. Press the ellipsis button of the ValuesExcluded property, add 12 in the Value Collection Editor that opens and press OK to close the editor.

10. The C1TextBox4 control also demonstrates another important feature unrelated to validation. Normally, we want to display a currency value in a Currency format (with dollar sign), but edit it as a simple number (no dollar sign). This is easy to do in C1Input. Just recall from Tutorial 4 that you can specify different formats for display and edit mode. Expand the DisplayFormat property, select None in its (Inherit) sub-property, and set DisplayFormat.FormatType = Currency.

11. In C1TextBox5 control validation is performed programmatically, in PostValidating event code. Set the PostValidation.Validation property to PostValidatingEvent and create the following event handler for the PostValidating event:

• Visual Basic

Private Sub C1TextBox5_PostValidating(ByVal sender As Object, ByVal e As C1.Win.C1Input.PostValidationEventArgs) Handles C1TextBox5.PostValidating If (CType(e.Value, Int16) < 0) Then e.ErrorInfo.ErrorMessage = "Value cannot be less than zero." ElseIf (CType(e.Value, Int16) > 5000) Then e.ErrorInfo.ErrorMessage = "Value cannot be greater than 5000." Else Return End If e.Succeeded = False End Sub

• C#

private void C1TextBox5_PostValidating(object sender, C1.Win.C1Input.PostValidationEventArgs e)

{

if ((Int16)e.Value < 0)

e.ErrorInfo.ErrorMessage = "Value cannot be less than zero.";

else if ((Int16)e.Value > 5000)

e.ErrorInfo.ErrorMessage = "Value cannot be greater than 5000.";

else

return;

e.Succeeded = false;

}

• Delphi

procedure TWinForm.C1TextBox5_PostValidating(sender: System.Object; e: C1.Win.C1Input.PostValidationEventArgs);

begin

if (Integer(e.Value) < 0) then

e.ErrorInfo.ErrorMessage := 'Value cannot be less than zero.'

Tutorial 6 – Data Formatting and Parsing · 55

else if (Integer(e.Value) > 5000) then

e.ErrorInfo.ErrorMessage := 'Value cannot be greater than 5000.'

else

Exit;

e.Succeeded := false;

end;

This code verifies that the value lies between 0 and 5000. In case of an error, it sets the e.ErrorInfo.ErrorMessage property that makes the specified message text appear in the error message after the event. Setting e.Suceeded to False indicates that the code has detected a validation error.


• When any one of the validation conditions are not satisfied, an attempt to leave the control with incorrect value shows an error message box with caption “C1Input Validation Error” and a brief error description. In the C1TextBox5 control, the error message is one of the two specified in the code.

Tutorial 6 – Data Formatting and Parsing This tutorial demonstrates some options in formatting and parsing data.

1. Create a new Windows Application project. Place the following components on the form as shown in the figure: C1ExpressConnection (C1.Data.Express.C1ExpressConnection), C1ExpressTable1-2 (C1.Data.Express.C1ExpressTable), C1Label1-8 (C1.Win.C1Input.C1Label), C1TextBox1-5 (C1.Win.C1Input.C1TextBox), C1DbNavigator1-2 (C1.Win.C1Input.C1DbNavigator), groupBox1 (System.Windows.Forms.GroupBox), rbYesNo, rbTrueFalse, rbOnOff, rbOneZero, rbCustom (all of the type System.Windows.Forms.RadioButton), btnClose (System.Windows.Forms.Button). Note: For all label controls except C1Label2 and C1Label8, set the TextDetached property to True. This is necessary to set their Text property.




C1ExpressTable1.ConnectionComponent = C1ExpressConnection1 C1ExpressTable1.DbTableName = Products C1ExpressTable2.ConnectionComponent = C1ExpressConnection1 C1ExpressTable2.DbTableName = Order Details

4. Create a master-detail relation between C1ExpressTable1 (master) and C1ExpressTable2 (detail). Press the ellipsis button in the Relations property of the C1ExpressionConnection1 control to open the Relations dialog. In the dialog, select “Products” for Parent, “Order Details” for Child, add a join with ProductID for both Parent field and Child field, press OK to close the Relations dialog.


C1DbNavigator1.DataSource = C1ExpressConnection1 C1DbNavigator1.DataMember = _Products C1DbNavigator2.DataSource = C1ExpressConnection1 C1DbNavigator1.DataMember = _Products.Products - Order Details C1Label2.DataSource = C1ExpressConnection1 C1Label2.DataField = _Products.ProductName C1TextBox1.DataSource = C1ExpressConnection1 C1TextBox1.DataField = _Products.Discontinued C1TextBox3.DataSource = C1ExpressConnection1 C1TextBox3.DataField = _Products.Products - Order Details.UnitPrice C1TextBox4.DataSource = C1ExpressConnection1 C1TextBox4.DataField = _Products.Products - Order Details.Discount C1TextBox5.DataSource = C1ExpressConnection1 C1TextBox5.DataField = _Products.Products - Order Details.Quantity C1Label8.DataSource = C1ExpressConnection1 C1Label8.DataField = _Products.Products - Order Details.Quantity

6. For the C1TextBox1 control, bound to the Discontinued field, set the FormatType property to YesNo. This is a boolean format showing “Yes” for True and “No” for False. This will be the default format of the C1TextBox1 control, but we will also make provisions for a custom format, setting the CustomFormat property of the C1TextBox1 control to “Yep|Nope”. This custom format will be enabled when the FormatType property is set to CustomFormat, which will be done with radio buttons in the next step.

7. To switch the Discontinued field format between various boolean formats, use the radio buttons. Assign the following event handlers to the radio buttons’ Click events:

• Visual Basic

Private Sub rbYesNo_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles rbYesNo.Click C1TextBox1.FormatType = FormatTypeEnum.YesNo End Sub Private Sub rbTrueFalse_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles rbTrueFalse.Click C1TextBox1.FormatType = FormatTypeEnum.TrueFalse End Sub Private Sub rbOnOff_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles rbOnOff.Click

Tutorial 6 – Data Formatting and Parsing · 57

C1TextBox1.FormatType = FormatTypeEnum.OnOff End Sub Private Sub rbOneZero_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles rbOneZero.Click C1TextBox1.FormatType = FormatTypeEnum.Integer End Sub Private Sub rbCustom_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles rbCustom.Click C1TextBox1.FormatType = FormatTypeEnum.CustomFormat End Sub

• C#

// One handler for all buttons private void radioButton_Click(object sender, System.EventArgs e) { switch (((RadioButton)sender).Name) { case "rbYesNo": C1TextBox1.FormatType = FormatTypeEnum.YesNo; break; case "rbTrueFalse": C1TextBox1.FormatType = FormatTypeEnum.TrueFalse; break; case "rbOnOff": C1TextBox1.FormatType = FormatTypeEnum.OnOff; break; case "rbOneZero": C1TextBox1.FormatType = FormatTypeEnum.Integer; break; case "rbCustom": C1TextBox1.FormatType = FormatTypeEnum.CustomFormat; break; } }

• Delphi

// One handler for all buttons procedure TWinForm.RadioButton1_Click(sender: System.Object; e: System.EventArgs); begin if (sender = RadioButtonYesNo) then C1TextBox1.FormatType := FormatTypeEnum.YesNo else if (sender = RadioButtonTrueFalse) then C1TextBox1.FormatType := FormatTypeEnum.TrueFalse else if (sender = RadioButtonOnOff) then C1TextBox1.FormatType := FormatTypeEnum.OnOff else if (sender = RadioButtonInteger) then C1TextBox1.FormatType := FormatTypeEnum.Integer else if (sender = RadioButtonCustomFmt) then C1TextBox1.FormatType := FormatTypeEnum.CustomFormat; end;

8. For C1textBox3 bound to the UnitPrice field, set the FormatType to Currency. The currency format with dollar sign is used both in display and edit mode. For C1TextBox4 bound to Discount, select FormatType = Percent (values are displayed and entered times 100 with percent sign). Also, for C1TextBox5 bound to Quantity, select FormatType = Hexadecimal, so it will be represented in hexadecimal form (think of it as a kind of low-tech encryption; we, of course, need this rather unusual format for purely demonstrational purposes).


9. Now, to decipher the hexadecimal Quantity, we want to convert it to the normal decimal representation and display the decimal number in C1Label8 with suffix “(base 10)”. There is no standard or custom format for such representation, but we can define our own formatting in code, in the Formatting event. If we set FormatType = UseEvent, our code can perform whatever formatting we need. Create the following event handler:

• Visual Basic

Private Sub C1Label8_Formatting(ByVal sender As Object, ByVal e As C1.Win.C1Input.FormatEventArgs) Handles C1Label8.Formatting e.Text = e.Value.ToString() + " (base10)" End Sub

• C#

private void C1Label8_Formatting(object sender, C1.Win.C1Input.FormatEventArgs e) { e.Text = e.Value.ToString() + " (base10)"; }

• Delphi

procedure TWinForm.C1Label8_Formatting(sender: System.Object; e: C1.Win.C1Input.FormatEventArgs); begin e.Text := e.Value.ToString + ' (base10)'; end;

10. In the C1TextBox2 control we will show how you can allow entering dates in multiple formats. Since this control is unbound, you need to set its DataType property manually. Set the DataType property to DateTime. Initialize its value with the current date in code, in the Form_Load event:

• Visual Basic

Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load C1TextBox2.Value = DateTime.Now End Sub

• C#

private void Form1_Load(object sender, System.EventArgs e) { C1TextBox2.Value = DateTime.Now; }

• Delphi

procedure TWinForm.TWinForm_Load(sender: System.Object; e: System.EventArgs); begin C1TextBox2.Value := DateTime.Now end;

The DateTimeInput mode (see tutorial 4) only works with a single date format, so we need to turn it off setting DateTimeInput = False for the C1TextBox2 control. Set the custom format as follows:

C1TextBox2.FormatType = CustomFormat C1TextBox2.CustomFormat = MM/dd/yyyy|d-MMM-yyyy|d.M.yy

This is a list of allowed formats separated with ‘|’. Parsing an input string, all formats will be tried until a matching one found. Formatting values for display, we obviously need a single format, so only the first format will be used for formatting.

Tutorial 7 - Using C1DateEdit and C1NumericEdit Controls · 59

We also want the control to display the date in LongDate format when not in focus. Expand the DisplayFormat property, then expand its (Inherit) sub-property, set the FormatType flag to False. This will make DisplayFormat.FormatType modifiable. then set DisplayFormat.FormatType to LongDate. Now the control shows its date value in long format when not in focus, in the first short format when in focus, and the user can type data in any of the three allowed sort formats.


• By selecting different radio buttons you can see how Discontinued is shown in different formats. The currently selected format also determines how Discontinued values can be entered by the user. Note also that you can enter boolean values in abbreviated form, just the initial letter is enough for all formats except On/Off where you need to enter the first two letters. Using the 1/0 format, entering any number except 0 results in a True value, which corresponds to the standard .NET conversion from integer to boolean.

• In the UnitPrice field you can enter or omit the dollar sign. Negative numbers can be entered both with minus sign and in parentheses, according to financial conventions.

• The Discount field allows you to enter the optional percent sign. When you enter a value in percent, it is automatically divided by 100 when it is saved in the data source.

• You can enter the date in the control at the bottom in any of the three allowed formats, as it is most convenient to you. For instance June 5, 2002 can be entered as 06/05/2002, or 5-Jun-2002, or 5.6.02.

Tutorial 7 - Using C1DateEdit and C1NumericEdit Controls The C1DateEdit control provides enhanced date-time editing capabilties. It derives from C1TextBox, so it supports DateTimeInput with separate fields for year, month, date, etc, and all options for formatting and parsing date-time values. In addition to that, it enables the user to select date in a dropdown calendar, and also to increment/decrement date fields in DateTimeInput mode with up/down buttons.

The C1NumericEdit control is specialized for numeric input. It also derives from C1TextBox, which enables it with formatting, parsing and validation functionality. In addition to that, it allows the user to increment/decrement the value by a specified amount using the up/down buttons, and to use a dropdown calculator to calculate values.

1. Create a new Windows Application project. Place the following components on the form as shown in the figure: C1ExpressConnection (C1.Data.Express.C1ExpressConnection), C1ExpressTable1-2 (C1.Data.Express.C1ExpressTable), C1Label1-11 (C1.Win.C1Input.C1Label), C1DateEdit1-3 (C1.Win.C1Input.C1DateEdit), C1NumericEdit1-3 (C1.Win.C1Input.C1NumericEdit), C1DbNavigator1-2 (C1.Win.C1Input.C1DbNavigator), button1 (System.Windows.Forms.Button). Note: For all label controls except C1Label10 and C1Label11, set the TextDetached property to True. This is necessary to set their Text property.




C1ExpressTable1.ConnectionComponent = C1ExpressConnection1 C1ExpressTable1.DbTableName = Orders C1ExpressTable2.ConnectionComponent = C1ExpressConnection1 C1ExpressTable2.DbTableName = Order Details

Create a master-detail relation between C1ExpressTable1 (master) and C1ExpressTable2 (detail). Press the ellipsis button in the Relations property of the C1ExpressionConnection1 control to open the Relations dialog. In the dialog, select “Orders” for Parent, “Order Details” for Child, add a join with OrderID for both Parent field and Child field, press OK to close the Relations dialog.

4. To bind controls to the data source, set these properties:

C1DbNavigator1.DataSource = C1ExpressConnection1 C1DbNavigator1.DataMember = _Orders C1DbNavigator2.DataSource = C1ExpressConnection1 C1DbNavigator1.DataMember = _Orders.Orders - Order Details C1Label10.DataSource = C1ExpressConnection1 C1Label10.DataField = _Orders.OrderID C1DateEdit1.DataSource = C1ExpressConnection1 C1DateEdit1.DataField = _Orders.OrderDate C1DateEdit2.DataSource = C1ExpressConnection1 C1DateEdit2.DataField = _Orders.RequiredDate C1DateEdit3.DataSource = C1ExpressConnection1 C1DateEdit3.DataField = _Orders.ShippedDate C1NumericEdit1.DataSource = C1ExpressConnection1

Tutorial 7 - Using C1DateEdit and C1NumericEdit Controls · 61

C1NumericEdit1.DataField = _Products.Products - Order Details.Quantity C1Label11.DataSource = C1ExpressConnection1 C1Label11.DataField = _Orders.Orders - Order Details.ProductID C1NumericEdit2.DataSource = C1ExpressConnection1 C1NumericEdit2.DataField = _Orders.Orders - Order Details.Quantity C1NumericEdit3.DataSource = C1ExpressConnection1 C1NumericEdit3.DataField = _Orders.Orders - Order Details.UnitPrice

5. Set up the OrderDate field (C1DateEdit1) for a simple date input with a dropdown calendar as the main means of entering a date. Turn off the DateTimeInput mode setting the DateTimeInput property to False. Make the calendar center-aligned relative to the control by setting the DropDownAlign property to Center.

6. The next control, C1DateEdit2 (RequiredDate field) will serve as a regular date-time input control, in DateTimeInput mode, without a dropdown calendar. Set the ShowDropDownButton property to False. To use the long date format, set the FormatType property to LongDate.

7. The ShippedDate field (control C1DateEdit3) will contain dates in MediumDate format (set its FormatType property to MediumDate), with up/down buttons and a dropdown calendar. Since ShippedDate can be NULL (DBNull), set the EmptyAsNull property to True. Then clearing the control contents will be equivalent to entering null value. Suppose we want certain days to appear bold in the dropdown calendar. To do that, expand the Calendar property, select the calendar property MonthlyBoldedDates and add two dates to the array using the collection editor dialog.

8. Now we will set up controls for numeric input. The C1NumericEdit1 control is bound to the Freight field. Set its FormatType to Currency and hide the up/down buttons (it does not make much sense for them to be a currency value) setting ShowUpDownButtons to False. Set the TextAlign property to Right. Also set the DropDownAlign property to Right to make the dropdown calculator right-aligned as well.

9. The Quantity field (C1NumericEdit2) does not need a dropdown calculator, so hide it setting the ShowDropDownButton to False. Since Quantity is an integer number, set the FormatType property to Integer. Set the increment for up/down buttons to a certain value you prefer, for example, to 3. You can also change the control’s appearance if you feel inclined to, for example, setting the BorderStyle property to FixedSingle.

10. The last field (C1NumericEdit3) allows the user to enter a currency value UnitPrice using a dropdown calculator. Set the FormatType property to Currency. As in the previous control, set the BorderStyle property to FixedSingle, just to see that you have all the usual appearance options at your disposal. Hide the up/down buttons (unnecessary for a currency field) setting the ShowUpDownButtons property to False. To center the dropdown calendar relative to the control, set the DropDownAlign property to Center.


• The OrderDate field allows you to enter a date from the keyboard, or open the dropdown calendar and select a date there with the mouse or arrow keys. In the dropdown calendar you can see the buttons for changing the month and year. At the bottom of the calendar you see the Clear and Today button. The Clear button sets the Value to DBNull, and the Today button sets it to the today’s date (that can be overridden in the Calendar.TodayDate property).

• Select a date field in RequiredDate and press the up/down buttons. Notice that you can enter a date without using keyboard.

• In the dropdown calendar in ShippedDate, you can see two bolded dates.

• Opening the dropdown calculator in the Freight and Quantity fields, you can see different button styles in the calculator.


Tutorial 8 – Custom Dropdown Form C1DropDownControl is a control derived from C1TextBox, so it supports all its formatting, validation and other features. As the other two C1TextBox-derived controls, it also supports up-down and dropdown buttons. However, unlike those specialized controls, C1DropDownControl allows you to attach your own logic to the UpDown button and your own dropdown form/editor to the dropdown button.

In this tutorial we will create a form that can be used to show a list of MRU (most recently used) values. Note that although we will use this form in only one control, the same form without modification can be used in any number of controls in your projects.

Note: Before opening Form1 at design time, you need to compile the tutorial project. Otherwise a “class not found” error will appear. This is because the dropdown form class needs to be compiled to become available in the DropDownFormClass property of a C1DropDownControl.

1. Create a new Windows Application project. Place a C1DropDownControl on the form, c1DropDownControl1.

2. Add a form derived from DropDownForm to your project. First add a new form MRUDropDown using the Add New Item from the File menu, then replace the class definition line(s) in the form code:

• Visual Basic

Public Class MRUDropDown Inherits System.Windows.Forms.Form

• C#

public class MRUDropDown : System.Windows.Forms.Form

• Delphi

TMRUDropDown = class(System.Windows.Forms.Form)with:

• Visual Basic

Public Class MRUDropDown Inherits C1.Win.C1Input.DropDownForm

• C#

public class MRUDropDown : C1.Win.C1Input.DropDownForm

• Delphi

TMRUDropDown = class(C1.Win.C1Input.DropDownForm)

3. Go to the Properties window and select the Options property of the MRUDropDown form. Set option Focusable to False and option AutoResize to True. The AutoResize option will make the width of the dropdown always equal the width of the control, and Focusable = False is needed because we do not want the dropdown form to take input focus. Instead, we want focus to remain in the control so the user can type in the control and select from the dropdown at the same time.

4. Place a ListBox control listBox1 on the dropdown form. Set listBox1 properties

listBox1.DockStyle = Fill listBox1.IntegralHeight = False listBox1.BorderStyle = None

These are appearance settings to make the list box occupy the whole dropdown area.

Tutorial 8 – Custom Dropdown Form · 63

5. To make the form open automatically when the user starts typing in the control, use the OwnerControlTextChanged event, add the following event handler:

• Visual Basic

Private Sub MRUDropDown_OwnerControlTextChanged(ByVal sender As Object, ByVal e As System.EventArgs) Handles MyBase.OwnerControlTextChanged OwnerControl.OpenDropDown() listBox1.SelectedIndex = listBox1.FindString(OwnerControl.Text) End Sub

• C#

private void MRUDropDown_OwnerControlTextChanged(object sender, System.EventArgs e) { OwnerControl.OpenDropDown(); listBox1.SelectedIndex = listBox1.FindString(OwnerControl.Text); }

• Delphi

procedure TMRUDropDown.TMRUDropDown_OwnerControlTextChanged(sender: System.Object; e: System.EventArgs); begin OwnerControl.OpenDropDown; ListBox1.SelectedIndex := ListBox1.FindString(OwnerControl.Text); end;

The second line selects the list box item corresponding to the current control text, if such item already exists.

6. To enable visual feedback while the user moves the mouse inside the list box, add the following event handler:

• Visual Basic

Private Sub listBox1_MouseMove(ByVal sender As Object,ByVal e As System.Windows.Forms.MouseEventArgs) Handles listBox1.MouseMove listBox1.SelectedIndex = listBox1.IndexFromPoint(e.X, e.Y) End Sub

• C#

private void listBox1_MouseMove(object sender, System.Windows.Forms.MouseEventArgs e) { listBox1.SelectedIndex = listBox1.IndexFromPoint(e.X, e.Y); }

• Delphi

procedure TMRUDropDown.ListBox1_MouseMove(sender: System.Object; e: System.Windows. Forms.MouseEventArgs); begin ListBox1.SelectedIndex := ListBox1.IndexFromPoint(e.X, e.Y); end;


7. To enable visual feedback while the user moves the mouse inside the list box, add the following event handler:

• Visual Basic

Private Sub listBox1_MouseMove(ByVal sender As Object,ByVal e As System.Windows.Forms.MouseEventArgs) Handles listBox1.MouseMove listBox1.SelectedIndex = listBox1.IndexFromPoint(e.X, e.Y) End Sub

• C#

private void listBox1_MouseMove(object sender, System.Windows.Forms.MouseEventArgs e) { listBox1.SelectedIndex = listBox1.IndexFromPoint(e.X, e.Y); }

• Delphi

procedure TMRUDropDown.ListBox1_MouseMove(sender: System.Object; e: System.Windows. Forms.MouseEventArgs); begin ListBox1.SelectedIndex := ListBox1.IndexFromPoint(e.X, e.Y); end;

8. To enable the user to navigate the dropdown list box with Up and Down keys and delete items with Ctrl-Del key, add the following event handler:

• Visual Basic

Private Sub MRUDropDown_KeyDown(ByVal sender As Object, ByVal e As System.Windows.Forms.KeyEventArgs) Handles MyBase.KeyDown If e.Modifiers = Keys.None And e.KeyCode = Keys.Up Then If listBox1.SelectedIndex > 0 Then listBox1.SelectedIndex = listBox1.SelectedIndex - 1 OwnerControl.Text = listBox1.Text OwnerControl.SelectAll() End If e.Handled = True End If If e.Modifiers = Keys.None And e.KeyCode = Keys.Down Then If listBox1.SelectedIndex < listBox1.Items.Count - 1 Then listBox1.SelectedIndex = listBox1.SelectedIndex + 1 OwnerControl.Text = listBox1.Text OwnerControl.SelectAll() End If e.Handled = True End If If e.Modifiers = Keys.Control And e.KeyCode = Keys.Delete _ And listBox1.SelectedIndex >= 0 Then listBox1.Items.RemoveAt(listBox1.SelectedIndex) e.Handled = True End If End Sub

• C#

private void MRUDropDown_KeyDown(object sender, System.Windows.Forms.KeyEventArgs e) { if (e.Modifiers == Keys.None && e.KeyCode == Keys.Up) { if (listBox1.SelectedIndex > 0) {

Tutorial 8 – Custom Dropdown Form · 65

listBox1.SelectedIndex--; OwnerControl.Text = listBox1.Text; OwnerControl.SelectAll(); } e.Handled = true; } if (e.Modifiers == Keys.None && e.KeyCode == Keys.Down) { if (listBox1.SelectedIndex < listBox1.Items.Count - 1) { listBox1.SelectedIndex++; OwnerControl.Text = listBox1.Text; OwnerControl.SelectAll(); } e.Handled = true; } if (e.Modifiers == Keys.Control && e.KeyCode == Keys.Delete && listBox1.SelectedIndex >= 0) { listBox1.Items.RemoveAt(listBox1.SelectedIndex); e.Handled = true; } }

• Delphi

procedure TMRUDropDown.MRUDropDown_KeyDown(sender: System.Object; e: System.Windows.F orms.KeyEventArgs); begin if ((e.Modifiers = Keys.None) And (e.KeyCode = Keys.Up)) then begin if (ListBox1.SelectedIndex > 0) then begin ListBox1.SelectedIndex := ListBox1.SelectedIndex - 1; OwnerControl.Text := listBox1.Text; OwnerControl.SelectAll; end; e.Handled := true; end; if ((e.Modifiers = Keys.None) And (e.KeyCode = Keys.Down)) then begin if (ListBox1.SelectedIndex < listBox1.Items.Count - 1) then begin listBox1.SelectedIndex := listBox1.SelectedIndex + 1; OwnerControl.Text := ListBox1.Text; OwnerControl.SelectAll; end; e.Handled := true; end; if ((e.Modifiers = Keys.Control) And (e.KeyCode = Keys.Delete) And (ListBox1.SelectedIndex >= 0)) then begin ListBox1.Items.RemoveAt(ListBox1.SelectedIndex); e.Handled := true; end; end;


9. To select an item and close the dropdown form when the user clicks a list box item, add the following event handler:

• Visual Basic

Private Sub listBox1_MouseDown(ByVal sender As Object, ByVal e As System.Windows.Forms.MouseEventArgs) Handles listBox1.MouseDown listBox1.SelectedIndex = listBox1.IndexFromPoint(e.X, e.Y) CloseDropDown(True) End Sub

• C#

private void listBox1_MouseDown(object sender, System.Windows.Forms.MouseEventArgs e) { listBox1.SelectedIndex = listBox1.IndexFromPoint(e.X, e.Y); CloseDropDown(true); }

• Delphi

procedure TMRUDropDown.ListBox1_MouseDown(sender: System.Object; e: System.Windows. Forms.MouseEventArgs); begin ListBox1.SelectedIndex := ListBox1.IndexFromPoint(e.X, e.Y); CloseDropDown(true); end;

10. To make the dropdown form actually change the control text when it is closed after the user clicks an item, add the following event handler for the PostChanges event:

• Visual Basic

Private Sub MRUDropDown_PostChanges(ByVal sender As Object, ByVal e As System.EventArgs) Handles MyBase.PostChanges If listBox1.SelectedIndex >= 0 Then OwnerControl.Value = listBox1.Text ElseIf listBox1.FindStringExact(OwnerControl.Text) < 0 Then listBox1.Items.Add(OwnerControl.Text) End If End Sub

• C#

private void MRUDropDown_PostChanges(object sender, System.EventArgs e) { if (listBox1.SelectedIndex >= 0) OwnerControl.Value = listBox1.Text; else if (listBox1.FindStringExact(OwnerControl.Text) < 0) listBox1.Items.Add(OwnerControl.Text); }

• Delphi

procedure MRUDropDown_PostChanges(sender: System.Object; e: System.EventArgs); begin if listBox1.SelectedIndex >= 0 then OwnerControl.Value := listBox1.Text else if listBox1.FindStringExact(OwnerControl.Text < 0 then listBox1.Items.Add(OwnerControl.Text); end;

Tutorial 9 – Editing Numbers in NumericInput Mode · 67

11. Now the dropdown form is ready and we can use it in the c1DropDownControl1 in Form1. Open Form1, select c1DropDownContor1, go to the Properties window and select the DropDownFormClass property. This property allows you to select a DropDownForm-derived form from your project. Select Tutorial8.MRUDropDown from the combo box. This is all you need to attach the dropdown form to a control. If needed, you can attach this form to any number of controls the same way.


• When you start typing, it automatically opens the dropdown list. The dropdown can also be opened with the dropdown button.

• After you type something in the control and press Enter, the next time you open the dropdown you see the typed item in the list.

• You can navigate the list with the mouse and with Up/Down keys, although the list dropdown does not have input focus, the focus remains in the control input area.

• Clicking a dropdown item with the mouse changes the control text.

Tutorial 9 – Editing Numbers in NumericInput Mode In this tutorial, you will learn how to use NumericInput mode for editing numeric data. C1TextBox and C1NumericEdit controls have a NumericInput property that is True by default. If NumericInput = True and DataType is a numeric type, the control functions in numeric mode facilitating typing of digits, decimal point and other numeric characters.

1. Create a new Windows Application project. Place the following components on the form as shown in the figure: c1ExpressTable1 (C1.Data.Express.C1ExpressTable), label1-6 (System.Windows.Forms.Label), c1DbNavigator1 (C1.Win.C1Input.C1DbNavigator), c1TextBox1-5 (C1.Win.C1Input.C1TextBox), c1Label1-3, lab1, lab2 (C1.Win.Input.C1Label), c1NumericEdit1-2 (C1.Win.C1Input.C1NumericEdit).


2. Select the c1ExpressTable1 component, go to the Properties window, open the ConnectionString property combo box and select <New Connection…>. It will open the standard OLE DB Data Link Properties dialog. Select the provider, the database and other necessary connection properties in that dialog. In these tutorials, we use the standard MS Access Northwind sample database (NWIND.MDB). Select “Microsoft Jet 4.0 OLE DB Provider” in the Provider tab, and “C:\Program Files\ComponentOne Studio.NET\Common\NWIND.MDB” (or another location, where your database is) in the Connection tab. Press OK. That will close the Data Link Properties dialog and put the connection string in the ConnectionString property. For the c1ExpressTable1 component, open the DbTableName property combo box and select "Order Details" from the database table list.


c1DbNavigator1.DataSource = c1ExpressTable1 c1TextBox1.DataSource = c1ExpressTable1 c1TextBox1.DataField = Quantity c1NumericEdit1.DataSource = c1ExpressTable1 c1NumericEdit1.DataField = Discount c1TextBox2.DataSource = c1ExpressTable1 c1TextBox2.DataField = UnitPrice

4. Adjust some appearance properties of the controls. Set BorderStyle to FixedSingle for the controls: label1-2, c1TextBox1-5, c1NumericEdit1-2. Expand the VisibleButtons property of c1DbNavigator1 and make two additional buttons visible: Apply and Cancel. Expand the UIStrings property of c1DbNavigator1 and replace "Row:" with "Order Item:". In c1NumericEdit1, set the ShowDropDownButton property to False (this control will have only up/down buttons, no dropdown). And vice versa, in c1NumericEdit2 we want to have only dropdown calculator, no up/down buttons, so we set its ShowUpDownButtons property to False.

5. c1TextBox1 represents an integer Quantity field. As an integer, it contains only digits, without decimal point and exponent. To specify integer format, set the c1TextBox1.FormatType to Integer.

6. c1NumericEdit1 is used for editing a Discount field that is represented as a percentage value. This is specified by setting c1NumericEdit1.FormatType to Percent. Also, specify the increment to be used to increase/decrease the value by a fixed amount using the Up/Down buttons: c1NumericEdit1.Increment = 0.0005. That will make the control’s Up/Down button increment/decrement the value by 0.05%.

7. c1TextBox2 is used to display and edit a UnitPrice field of Decimal type. To show it in currency format, with dollar sign, set c1TextBox2.FormatType = Currency. In this case, the currency sign shown in the value is defined by the current culture setting controlled by c1TextBox2.Culture property. If c1TextBox2.Culture = (Current Culture), current system regional settings are used.

8. There are several unbound, not bound to a data source controls in the bottom part of the form. c1NumericEdit2 edits numbers in scientific format, with decimal point and exponent. This control also includes a dropdown calculator. Set c1NumericEdit2.DataType = Decimal and c1NumericEdit2.FormatType = Scientific. By default, a number in scientific format contains six digits after decimal point and three digits in the exponent. If you need a non-default format, it can be defined in the CustomFormat property.

9. The c1TextBox3 control edits numbers in hexadecimal format. Set c1TextBox3.DataType = Int16 (16-bit integer number), c1TextBox3.FormatType = Hexadecimal. In this mode, the user will be able to type only digits 0-9, letters A-F, and minus sign (or change the sign of the number pressing F9). The C1Label control lab1 adjacent to c1TextBox3 shows the entered number in the usual decimal format. To connect it to the number, set lab1.DataType = Int16 and add an event handler for the ValueChanged event of the c1TextBox3 control:


• Visual Basic

Private Sub c1TextBox3_ValueChanged( ByVal sender As Object, ByVal e As System.EventArgs) Handles c1TextBox3.ValueChanged Try lab1.Value = c1TextBox3.Value Catch End Try End Sub

• C#

private void c1TextBox3_ValueChanged(object sender, System.EventArgs e) { try { lab1.Value = c1TextBox3.Value; } catch { } }

• Delphi

procedure TWinForm.C1TextBox3_ValueChanged(sender: System.Object; e: System.EventArgs); begin try lab1.Value := C1TextBox3.Value; except end; end;

10. The c1TextBox4 control demonstrates how you can change number format by changing culture settings used in formatting. Set c1TextBox4.DataType = Int32 and c1TextBox4.FormatType = StandardNumber. A number in this format has a sign, thousands separators and decimal point. Settings used for this formatting, such as the sign, thousand separator and decimal point characters, are defined by the current culture settings controlled by the Culture property. You can specify non-default culture settings handling the event c1TextBox4.CultureInfoSetup. For example, we can show negative numbers with the word “minus ” instead of the usual “-“. We will also suppress the fractional part of the number, and use “|” as thousands separator. We will also change the group sizes (so they are no longer thousands), make the first (rightmost) group contain one digit, second – two digits, third – three digits, and all the rest (higher) digits make a single group. This is done by the following event handler:

• Visual Basic

Private Sub c1TextBox4_CultureInfoSetup(ByVal sender As Object, ByVal e As C1.Win.C1Input.CultureInfoSetupEventArgs) Handles c1TextBox4.CultureInfoSetup Dim ci As CultureInfo = e.CultureInfo ci.NumberFormat.NegativeSign = " minus " ci.NumberFormat.NumberGroupSeparator = "|" ci.NumberFormat.NumberGroupSizes = New Integer() {1, 2, 3, 0} ci.NumberFormat.NumberDecimalDigits = 0 End Sub


• C#

private void c1TextBox4_CultureInfoSetup(object sender, C1.Win.C1Input.CultureInfoSetupEventArgs e) { CultureInfo ci = e.CultureInfo; ci.NumberFormat.NegativeSign = " minus "; ci.NumberFormat.NumberGroupSeparator = "|"; ci.NumberFormat.NumberGroupSizes = new int[] {1, 2, 3, 0}; ci.NumberFormat.NumberDecimalDigits = 0; }

• Delphi

procedure TWinForm.C1TextBox4_CultureInfoSetup(sender: System.Object; e: C1.Win.C1Input.CultureInfoSetupEventArgs); var ci: CultureInfo; r: Array of Integer; begin SetLength(r, 4); r[0] := 1; r[1] := 2; r[2] := 3; r[3] := 0; ci := e.CultureInfo; ci.NumberFormat.NegativeSign := ' minus '; ci.NumberFormat.NumberGroupSeparator := '|'; ci.NumberFormat.NumberGroupSizes := r; ci.NumberFormat.NumberDecimalDigits := 0; end;

11. c1TextBox5 shows how to specify a custom, non-standard number format. Set DataType = Decimal, FormatType = CustomFormat and CustomFormat = "#,##0,;(###0,);zero". In this format, three colon-separated parts define three different formats used, correspondingly, for positive, negative numbers and zero. Character ‘0’ denotes a required digit, character ‘#’ specifies an optional digit, and ‘,’ is the thousands separator. Thousands separator on the right means the number is stored as times 1000 the entered number (per separator). To see the number that is stored when we enter a number in c1TextBox5, we use a C1Label control lab2 adjacent to c1TextBox5, set lab2.DataType = Decimal and add an event handler for the ValueChanged event of the c1TextBox5 control:

• Visual Basic

Private Sub c1TextBox5_ValueChanged(ByVal sender As Object, ByVal e As System.EventArgs) Handles c1TextBox5.ValueChanged lab2.Value = c1TextBox5.Value End Sub

• C#

private void c1TextBox5_ValueChanged(object sender, System.EventArgs e) { lab2.Value = c1TextBox5.Value; }

• Delphi

procedure TWinForm.C1TextBox5_ValueChanged(sender: System.Object; e: System.EventArgs); begin lab2.Value := c1TextBox5.Value; end;



• The user cannot enter arbitrary text in NumericInput mode. For example, if you type a letter, it is ignored. Only characters allowed by the specified format are permitted.

• Using properties FormatType and CustomFormat, you can specify any standard or custom format supported in .NET (see “Numeric Format Strings” in .NET documentation). All these formats are used both for display and editing of numeric values.

• Changing culture settings, you can control literal characters used in formatting and various other format settings.

C1DropDownControl Control · 73

C1Input Reference The C1.Win.C1Input namespace contains the following classes:

C1DropDownControl Control Base class for C1DateEdit and C1NumericEdit controls. Includes support for dropdown and up/down buttons. See Dropdown and Increment Buttons (page 30).

System.Object System.MarshalByRefObject System.ComponentModel.Component System.Windows.Forms.Control System.Windows.Forms.TextBoxBase System.Windows.Forms.TextBox C1.Win.C1Input.C1TextBox C1.Win.C1Input.C1DropDownControl C1.Win.C1Input.C1DateEdit C1.Win.C1Input.C1NumericEdit

C1DropDownControl Members C1DropDownControl Properties (properties inherited from C1TextBox are not shown)

ButtonCursor The cursor that is displayed when the mouse is over a button.

DefaultDropDownFormClassName Specifies form class that is used by default as the dropdown for the control.

DropDownFormAlign Alignment of the dropdown form relative to the control.

DropDownForm Returns dropdown form instance associated with the control.

DropDownFormClassName Specifies the class name of a Form serving as the dropdown window.

DroppedDown Run-time read-only property indicating if the dropdown is currently open.

GapHeight Distance in pixels between the control edge and the dropdown.

InterceptArrowKeys Determines if the up/down buttons intercept and handle Up and Down arrow keys.

MouseClickPassThrough Gets or sets whether the mouse click event is consumed or passed through after closing the dropdown.

ShowDropDownButton Determines if the dropdown button is visible.

ShowModalButton Determines if the modal button is visible.

ShowUpDownButtons Determines if the up/down buttons are visible.

74 · C1Input Reference

VisibleButtons Enumeration specifying which buttons are visible.

C1DropDownControl Methods (methods inherited from C1TextBox are not shown)

CloseDropDown Closes the dropdown

OpenDropDown Shows the dropdown.

C1DropDownControl Events (events inherited from C1TextBox are not shown)

ButtonCursorChanged Occurs when the ButtonCursor property changes.

DropDownFormAlignChanged Occurs when the value of the DropDownFormAlign property has changed.

DropDownClosed Occurs when the dropdown has been closed.

DropDownOpened Occurs when the dropdown is opened

ModalButtonClick Occurs when the Modal button is clicked.

UpDownButtonClick Occurs when UpDown buttons are clicked.

C1DropDownControl Properties

DefaultDropDownFormClassName Property Specifies form class that is used by default as the dropdown for the control.

Syntax

[VB]

Overridable Protected ReadOnly Property DefaultDropDownFormClassName As String

[C#]

protected virtual string DefaultDropDownFormClassName {get;}

[Delphi]

property DefaultDropDownFormClassName: string;

Remarks

This property is overridden in the C1NumericEdit and C1DateEdit controls. It returns a calculator form in C1NumericEdit and a calendar form in C1DateEdit. If you create your own custom control derived from C1DropDown, you can override this property to specify the dropdown form used by your custom control. The value, if non-empty, must be a full class name including namespace. The class must derive from C1.Win.C1Input.DropDownForm. If the DropDownFormClassName is set, it overrides the default dropdown.

DropDownFormAlign Property · 75

See Also

C1DropDownControl Control (page 73)

DropDownFormAlign Property Alignment of the dropdown form relative to the control.

Syntax

[VB]

Public Property DropDownFormAlign As DropDownFormAlignmentEnum

[C#]

public DropDownFormAlignmentEnum DropDownFormAlign {get; set;}

[Delphi]

property DropDownFormAlign: DropDownFormAlignmentEnum;

Remarks

If this property is set to Default, the form's DropDownForm.DropDownAlign property is used.

See Also

C1DateEdit Control (page 82)


C1NumericEdit Control (page 92)

DropDownForm Property Returns dropdown form instance associated with the control.

Syntax

[VB]

Overridable Public Property DropDownForm As DropDownForm

[C#]

public virtual DropDownForm DropDownForm {get; set;}

[Delphi]

property DropDownForm: DropDownForm;

See Also



DropDownFormClassName Property Specifies the class name of a Form serving as the dropdown window.

Syntax

[VB]

Public Property DropDownFormClassName As String

[C#]

public string DropDownFormClassName {get; set;}

[Delphi]

property DropDownFormClassName: string;

Remarks

The class must be derived from C1.Win.C1Input.DropDownForm.

See Also


DroppedDown Property Run-time read-only property indicating if the dropdown is currently open.

Syntax

[VB]

Public ReadOnly Property DroppedDown As Boolean

[C#]

public bool DroppedDown {get;}

[Delphi]

property DroppedDown: Boolean;

See Also




GapHeight Property Distance in pixels between the control edge and the dropdown.

Syntax

[VB]

Public Property GapHeight As Integer

[C#]

public int GapHeight {get; set;}

InterceptArrowKeys Property · 77

[Delphi]

property GapHeight: Integer;

See Also




InterceptArrowKeys Property Determines if the up/down buttons intercept and handle Up and Down arrow keys.

Syntax

[VB]

Public Property InterceptArrowKeys As Boolean

[C#]

public bool InterceptArrowKeys {get; set;}

[Delphi]

property InterceptArrowKeys: Boolean;

See Also




MouseClickPassThrough Property Gets or sets whether the mouse click event is consumed or passed through after closing the dropdown.

Syntax

[VB]

Public Property MouseClickPassThrough As Boolean

[C#]

public bool MouseClickPassThrough {get; set;}

[Delphi]

property MouseClickPassThrough: Boolean;

Remarks

Default value is false.

See Also





ShowDropDownButton Property Determines if the dropdown button is visible.

Syntax

[VB]

Public Property ShowDropDownButton As Boolean

[C#]

public bool ShowDropDownButton {get; set;}

[Delphi]

property ShowDropDownButton: Boolean;

See Also




ShowModalButton Property Determines if the modal button is visible.

Syntax

[VB]

Public Property ShowModalButton As Boolean

[C#]

public bool ShowModalButton {get; set;}

[Delphi]

property ShowModalButton: Boolean;

See Also




ShowUpDownButtons Property Determines if the up/down buttons are visible.

Syntax

[VB]

Public Property ShowUpDownButtons As Boolean

[C#]

public bool ShowUpDownButtons {get; set;}

VisibleButtons Property · 79

[Delphi]

property ShowUpDownButtons: Boolean;

See Also




VisibleButtons Property Enumeration specifying which buttons are visible. Default: (UpDown Or DropDown).

Syntax

[VB]

Public Property VisibleButtons As DropDownControlButtonFlags

[C#]

public DropDownControlButtonFlags VisibleButtons {get; set;}

[Delphi]

property VisibleButtons: DropDownControlButtonFlags;

See Also




C1DropDownControl Methods

CloseDropDown Method Closes the dropdown.

Syntax

[VB]

Public Sub CloseDropDown()

[C#]

public void CloseDropDown ()

[Delphi]

procedure CloseDropdown;

See Also





OpenDropDown Method Shows the dropdown.

Syntax

[VB]

Public Sub OpenDropDown()

[C#]

public void OpenDropDown()

[Delphi]

procedure OpenDropDown;

See Also




C1DropDownControl Events

DropDownFormAlignChanged Event Occurs when the value of the DropDownFormAlign property has changed.

Syntax

[VB]

Public Event DropDownFormAlignChanged As EventHandler

[C#]

public event EventHandler DropDownFormAlignChanged

[Delphi]

property DropDownFormAlignChanged: EventHandler;

See Also




DropDownClosed Event Occurs when the dropdown has been closed.

Syntax

[VB]

Public Event DropDownClosed As EventHandler

DropDownOpened Event · 81

[C#]

public event EventHandler DropDownClosed

[Delphi]

property DropDownClosed: EventHandler;

See Also




DropDownOpened Event Occurs just before the dropdown is opened.

Syntax

[VB]

Public Event DropDownOpened As EventHandler

[C#]

public event EventHandler DropDownOpened

[Delphi]

property DropDownOpened: EventHandler;

See Also




ModalButtonClick Event Occurs when the Modal button is clicked.

Syntax

[VB]

Public Event ModalButtonClick As EventHandler

[C#]

public event EventHandler ModalButtonClick

[Delphi]

property ModalButtonClick: EventHandler;

See Also





UpDownButtonClick Event Occurs when UpDown buttons are clicked.

Syntax

[VB]

Public Event UpDownButtonClick(sender As Object, e As UpDownButtonClickEventArgs) As UpDownButtonClickEventHandler

[C#]

public event UpDownButtonClickEventHandler UpDownButtonClick

[Delphi]

property UpDownButtonClick: UpDownButtonClickEventHandler;

See Also




C1DateEdit Control Displays and edits date and/or time values. Includes a dropdown calendar for easy input of datetime values.

System.Object System.MarshalByRefObject System.ComponentModel.Component System.Windows.Forms.Control System.Windows.Forms.TextBoxBase System.Windows.Forms.TextBox C1.Win.C1Input.C1TextBox C1.Win.C1Input.C1DropDownControl C1.Win.C1Input.C1DateEdit

C1DateEdit Members C1DateEdit Properties

AcceptsEscape (inherited from C1TextBox) Indicates if the Escape key that cancels modified value is handled by the control without passing it to the owner form (AcceptsEscape=True), or if it is then passed to the form so it can be closed if the form has CancelButton (AcceptsEscape=False).

AcceptsTab (inherited from C1TextBox) If True, Tab and Shift+Tab keys move the focused position within the edit mask or in DateTimeInput mode between groups of input characters.

AccessibilityObject (inherited from Control) Gets the AccessibleObject assigned to the control.

AccessibleDefaultActionDescription (inherited from Control)

Gets or sets the default action description of the control for use by accessibility client applications.

C1DateEdit Control · 83

AccessibleDescription (inherited from Control)

Gets or sets the description of the control used by accessibility client applications.

AccessibleName (inherited from Control) Gets or sets the name of the control used by accessibility client applications.

AccessibleRole (inherited from Control) Gets or sets the accessible role of the control.

AllowDbNull (inherited from C1TextBox) Determines whether it is possible to enter DBNull value in the control.

AllowDrop (inherited from Control) Gets or sets a value indicating whether the control can accept data that the user drags onto it.

Anchor (inherited from Control) Gets or sets which edges of the control are anchored to the edges of its container.

AutoSize (inherited from TextBoxBase) Gets or sets a value indicating whether the height of the control automatically adjusts when the font assigned to the control is changed.

BackColor (inherited from TextBoxBase) Gets or sets the background color of the control.

BackgroundImage (inherited from Control) Gets or sets the background image displayed in the control.

BindingContext (inherited from Control) Gets or sets the BindingContext for the control.

BorderStyle (inherited from TextBoxBase) Gets or sets the border type of the text box control.

Bottom (inherited from Control) Gets the distance between the bottom edge of the control and the top edge of its container's client area.

Bounds (inherited from Control) Gets or sets the size and location of the control.

ButtonCursor (inherited from C1DropDownControl)

The cursor that is displayed when the mouse is over a button.

Calendar The dropdown calendar object.

CanFocus (inherited from Control) Gets a value indicating whether the control can receive focus.

CanSelect (inherited from Control) Gets a value indicating whether the control can be selected.

CanUndo (inherited from TextBoxBase) Gets a value indicating whether the user can undo the previous operation in a text box control.

Capture (inherited from Control) Gets or sets a value indicating whether the control has captured the mouse.

CaseSensitive (inherited from C1TextBox) True if string comparisons are case-sensitive; otherwise, False.

ClientRectangle (inherited from Control) Gets the rectangle that represents the client area of the control.

ClientSize (inherited from Control) Gets or sets the height and width of the client area of the control.

CompanyName (inherited from Control) Gets the name of the company or creator of the application containing the control.

Container (inherited from Component) Gets the IContainer that contains the Component.


ContainsFocus (inherited from Control) Gets a value indicating whether the control, or one of its child controls, currently has the input focus.

ContextMenu (inherited from Control) Gets or sets the shortcut menu associated with the control.

Controls (inherited from Control) Gets the collection of controls contained within the control.

CopyWithLiterals (inherited from Control) Used with numeric input mode and edit mask. If True, text in the clipboard includes literals.

Created (inherited from Control) Gets a value indicating whether the control has been created.

Culture (inherited from C1TextBox) The culture ID.

CultureInfo (inherited from C1TextBox) The current CultureInfo object.

CultureName (inherited from C1TextBox) The name selected for the Culture property in the Properties grid.

CurrentTimeZone (inherited from C1TextBox)

If True, the control’s stored Value is in current time zone; otherwise, the Value is adjusted to the time zone defined by the GMTOffset property.

Cursor (inherited from Control) Gets or sets the cursor that is displayed when the mouse pointer is over the control.

CustomFormat (inherited from C1TextBox) Custom format specifier used if FormatType = FormatTypeEnum.CustomFormat.

DataBindings (inherited from Control) Gets the data bindings for the control.

DataField (inherited from C1TextBox) The field of the data source object to which the control is bound.

DataSource (inherited from C1TextBox) The data source object to which the control is bound.

DateTimeInput (inherited from C1TextBox) Whether or not a special edit mode is applied to DateTime values.

DaylightTimeAdjustment The value specified in the GMTOffset property can be advanced or set back due to daylight-saving time changes.

DisplayFormat (inherited from C1TextBox) Format used to display the value when the control is not in edit mode.

DisplayRectangle (inherited from Control) Gets the rectangle that represents the display area of the control.

Disposing (inherited from Control) Gets a value indicating whether the control is in the process of being disposed of.

Dock (inherited from Control) Gets or sets which edge of the parent container a control is docked to.

DropDownFormAlign (inherited from C1DropDownControl)

Alignment of the dropdown relative to the control.

DroppedDown (inherited from C1DropDownControl)

Run-time read-only property indicating if the dropdown is currently open.


EditFormat (inherited from C1TextBox) Format used to display the value when the control is in edit mode (has input focus and is not read-only).

EditMask (inherited from C1TextBox) The edit mask string restricting user input.

EditMode (inherited from C1TextBox) Returns True, if the control has input focus and TextDetached = False.

EmptyAsNull (inherited from C1TextBox) If True, empty strings are interpreted as null values (DBNull).

Enabled (inherited from Control) Gets or sets a value indicating whether the control can respond to user interaction.

ErrorInfo (inherited from C1TextBox) Settings affecting error handling in the control.

Focused (inherited from Control) Gets a value indicating whether the control has input focus.

Font (inherited from Control) Gets or sets the font of the text displayed by the control.

ForeColor (inherited from TextBoxBase) Gets or sets the foreground color of the control.

FormatType (inherited from C1TextBox) Enumeration value determining the formatting method, including standard .NET format specifiers, custom and programmatic formatting.

GapHeight (inherited from C1DropDownControl)

Distance in pixels between the control edge and the dropdown.

GMTOffset (inherited from C1TextBox) The time zone of the Value property used if CurrentTimeZone = False.

Handle (inherited from Control) Gets the window handle that the control is bound to.

HasChildren (inherited from Control) Gets a value indicating whether the control contains one or more child controls.

Height (inherited from Control) Gets or sets the height of the control.

HideSelection (inherited from TextBoxBase) Gets or sets a value indicating whether the selected text in the text box control remains highlighted when the control loses focus.

ImeMode (inherited from Control) Gets or sets the Input Method Editor (IME) mode of the control.

InitialSelection (inherited from C1TextBox) Determines the selection position when a control receives input focus.

InterceptArrowKeys (inherited from C1DropDownControl)

Determines if the up/down buttons intercept and handle Up and Down arrow keys.

InvokeRequired (inherited from Control) Gets a value indicating whether the caller must call an invoke method when making method calls to the control because the caller is on a different thread than the one the control was created on.

IsAccessible (inherited from Control) Gets or sets a value indicating whether the control is visible to accessibility applications.

IsDisposed (inherited from Control) Gets a value indicating whether the control has been disposed of.


IsHandleCreated (inherited from Control) Gets a value indicating whether the control has a handle associated with it.

Label (inherited from C1TextBox) Label control associated with this input field.

Left (inherited from Control) Gets or sets the x-coordinate of a control's left edge in pixels.

Location (inherited from Control) Gets or sets the coordinates of the upper-left corner of the control relative to the upper-left corner of its container.

Margins (inherited from C1TextBox) The spacing between the input control content and its edges, in pixels.

MaskInfo (inherited from C1TextBox) Edit mask settings.

MaxLength (inherited from TextBoxBase) Gets or sets the maximum number of characters the user can type into the text box control.

MinShortYear (inherited from C1TextBox) The minimum year that can be entered without leading zeros.

Modified (inherited from C1TextBox) Gets or sets a value that indicates that the control has been modified by the user since the control received the input focus or its Value last set.

Name (inherited from Control) Gets or sets the name of the control.

NullText (inherited from C1TextBox) String representing a DBNull value.

Parent (inherited from Control) Gets or sets the parent container of the control.

ParseInfo (inherited from C1TextBox) Settings affecting parsing, that is, converting the string entered by the user to the data type.

PostValidation (inherited from C1TextBox) Validation rules applied after parsing, that is, after converting the string entered by the user to the DataType (typed validation).

PreferredHeight (inherited from TextBoxBase)

Gets the preferred height for a single-line text box.

PreValidation (inherited from C1TextBox) Validation rules applied before parsing, that is, before converting the string entered by the user to the DataType (raw string validation).

ProductName (inherited from Control) Gets the product name of the assembly containing the control.

ProductVersion (inherited from Control) Gets the version of the assembly containing the control.

ReadOnly (inherited from TextBoxBase) Gets or sets a value indicating whether text in the text box is read-only.

RecreatingHandle (inherited from Control) Gets a value indicating whether the control is currently re-creating its handle.

Region (inherited from Control) Gets or sets the window region associated with the control.

Right (inherited from Control) Gets the distance between the right edge of the control and the left edge of its container.


RightToLeft (inherited from Control) Gets or sets a value indicating whether control's elements are aligned to support locales using right-to-left fonts.

SelectedText (inherited from TextBoxBase) Gets or sets a value indicating the currently selected text in the control.

SelectionLength (inherited from TextBoxBase)

Gets or sets the number of characters selected in the text box.

SelectionStart (inherited from TextBoxBase) Gets or sets the starting point of text selected in the text box.

ShowDropDownButton (inherited from C1DropDownControl)

Determines if the dropdown button is visible.

ShowModalButton (inherited from C1DropDownControl)

Determines if the modal button is visible.

ShowUpDownButtons (inherited from C1DropDownControl)

Determines if the up/down buttons are visible.

Site (inherited from Control) Gets or sets the site of the control.

Size (inherited from Control) Gets or sets the height and width of the control.

TabIndex (inherited from Control) Gets or sets the tab order of the control within its container.

TabStop (inherited from Control) Gets or sets a value indicating whether the user can give the focus to this control using the TAB key.

Tag (inherited from Control) Gets or sets the object that contains data about the control.

Text (inherited from C1TextBox) The current text in the control.

TextAlign (inherited from TextBox) Gets or sets how text is aligned in a TextBox control.

TextLength (inherited from TextBoxBase) Gets the length of text in the control.

Top (inherited from Control) Gets or sets the y-coordinate of the control's top edge in pixels.

TopLevelControl (inherited from Control) Gets the parent control that is not parented by another Windows Forms control. Typically, this is the outermost Form that the control is contained in.

TrimEnd (inherited from C1TextBox) If True, trailing spaces are removed.

TrimStart (inherited from C1TextBox) If True, leading spaces are removed.

UserCultureOverride (inherited from C1TextBox)

If True, current user regional settings override the selected culture.

Value (inherited from C1TextBox) The main bindable property of a C1Input control.

ValueIsDbNull (inherited from C1TextBox) Gets or sets a value indicating whether the Value is DBNull.

VerticalAlign (inherited from C1TextBox) Vertical alignment of the contents in the control.

Visible (inherited from Control) Gets or sets a value indicating whether the control is displayed.


VisibleButtons (inherited from C1DropDownControl)

Enumeration specifying which buttons are visible.

Width (inherited from Control) Gets or sets the width of the control.

C1DateEdit Methods

AppendText (inherited from TextBoxBase) Appends text to the current text of text box.

BeginInvoke (inherited from Control) Executes a delegate asynchronously on the thread that the control's underlying handle was created on.

BringToFront (inherited from Control) Brings the control to the front of the z-order.

CheckValidationResult (inherited from C1TextBox)

Checks the result of the ParseContent method.

Clear (inherited from TextBoxBase) Clears all text from the text box control.

ClearUndo (inherited from TextBoxBase) Clears information about the most recent operation from the undo buffer of the text box.

CloseDropDown (inherited from C1DropDownControl)

Closes the dropdown.

Contains (inherited from Control) Retrieves a value indicating whether the specified control is a child of the control.

Copy (inherited from TextBoxBase) Copies the current selection in the text box to the Clipboard.

CreateControl (inherited from Control) Forces the creation of the control, including the creation of the handle and any child controls.

CreateGraphics (inherited from Control) Creates the Graphics object for the control.

CreateObjRef (inherited from MarshalByRefObject)

Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.

Cut (inherited from TextBoxBase) Moves the current selection in the text box to the Clipboard.

DecDateTimeInput (inherited from C1TextBox)

Decrements the currently selected field in DateTimeInput mode.

Dispose (inherited from Component) Releases the resources used by the Component.

DoDragDrop (inherited from Control) Begins a drag-and-drop operation.

EndInvoke (inherited from Control) Retrieves the return value of the asynchronous operation represented by the IAsyncResult object passed.

Equals (inherited from Object) Determines whether two Object instances are equal.

FindForm (inherited from Control) Retrieves the form that the control is on.

Focus (inherited from Control) Sets input focus to the control.

GetChildAtPoint (inherited from Control) Retrieves the child control that is located at the specified coordinates.


GetContainerControl (inherited from Control) Returns the next ContainerControl up the control's chain of parent controls.

GetHashCode (inherited from Object) Serves as a hash function for a particular type, suitable for use in hashing algorithms and data structures like a hash table.

GetLifetimeService (inherited from MarshalByRefObject)

Retrieves the current lifetime service object that controls the lifetime policy for this instance.

GetNextControl (inherited from Control) Retrieves the next control forward or back in the tab order of child controls.

GetType (inherited from Object) Gets the Type of the current instance.

Hide (inherited from Control) Conceals the control from the user.

IncDateTimeInput (inherited from C1TextBox)

Decrements the currently selected field in DateTimeInput mode.

InitializeLifetimeService (inherited from MarshalByRefObject)

Obtains a lifetime service object to control the lifetime policy for this instance.

Invalidate (inherited from Control) Invalidates a specific region of the control and causes a paint message to be sent to the control.

Invoke (inherited from Control) Executes a delegate on the thread that owns the control's underlying window handle.

OpenDropDown (inherited from C1DropDownControl)

Shows the dropdown.

ParseContent (inherited from C1TextBox) Parses the Text string.

Paste (inherited from TextBoxBase) Replaces the current selection in the text box with the contents of the Clipboard.

PerformLayout (inherited from Control) Forces the control to apply layout logic to child controls.

PointToClient (inherited from Control) Computes the location of the specified screen point into client coordinates.

PointToScreen (inherited from Control) Computes the location of the specified client point into screen coordinates.

PreProcessMessage (inherited from Control) Preprocesses input messages within the message loop before they are dispatched.

RectangleToClient (inherited from Control) Computes the size and location of the specified screen rectangle in client coordinates.

RectangleToScreen (inherited from Control) Computes the size and location of the specified client rectangle in screen coordinates.

Refresh (inherited from Control) Forces the control to invalidate its client area and immediately redraw itself and any child controls.

ResetBackColor (inherited from Control) Resets the BackColor property to its default value.

ResetBindings (inherited from Control) Resets the DataBindings property to its default value.

ResetCursor (inherited from Control) Resets the Cursor property to its default value.

ResetFont (inherited from Control) Resets the Font property to its default value.

ResetForeColor (inherited from Control) Resets the ForeColor property to its default value.


ResetImeMode (inherited from Control) Resets the ImeMode property to its default value.

ResetRightToLeft (inherited from Control) Resets the RightToLeft property to its default value.

ResetText (inherited from C1TextBox) Updates the control's Text with the current Value.

ResumeLayout (inherited from Control) Resumes normal layout logic.

Scale (inherited from Control) Scales the control and any child controls.

ScrollToCaret (inherited from TextBoxBase) Scrolls the contents of the control to the current caret position.

Select (inherited from TextBoxBase) Selects text within the control.

SelectAll (inherited from TextBoxBase) Selects all text in the text box.

SelectNextControl (inherited from Control) Activates the next control.

SendToBack (inherited from Control) Sends the control to the back of the z-order.

SetBounds (inherited from Control) Sets the bounds of the control.

SetProposedValue (inherited from C1TextBox)

Works exactly as setting the Value property, except that it does not change the internal variable storing the value before editing, so the user can press Esc and restore the previous value.

Show (inherited from Control) Displays the control to the user.

SuspendLayout (inherited from Control) Temporarily suspends the layout logic for the control.

ToString (inherited from Object) Returns a String that represents the current Object.

Undo (inherited from TextBoxBase) Undoes the last edit operation in the text box.

Update (inherited from Control) Causes the control to redraw the invalidated regions with its client area.

UpdateValueWithCurrentText (inherited from C1TextBox)

Triggers parsing of the Text property and updating the Value.

C1DateEdit Events (events inherited from Control are not shown)

AutoSizeChanged (inherited from TextBoxBase)

Occurs when the value of the AutoSize property has changed.

BorderStyleChanged (inherited from TextBoxBase)

Occurs when the value of the BorderStyle property has changed.

ButtonCursorChanged (inherited from C1DropDownControl)

Occurs when the ButtonCursor property changes.

Click (inherited from TextBoxBase) Occurs when the text box is clicked.

ContextMenuChanged (inherited from Control)

Occurs when the value of the ContextMenu property changes.

CultureInfoSetup (inherited from C1TextBox)

CultureInfo can be set up (on startup) or has been changed.

DropDownFormAlignChanged (inherited from C1DropDownControl)

Occurs when the value of the DropDownFormAlign property has changed.


DropDownClosed (inherited from C1DropDownControl)

Occurs when the dropdown has been closed.

DropDownOpened (inherited from C1DropDownControl)

Occurs before the dropdown is opened.

FormatError (inherited from C1TextBox) Occurs when the control receives data that cannot be formatted according to the current format and edit mask settings.

Formatted (inherited from C1TextBox) Occurs after the value has been formatted.

Formatting (inherited from C1TextBox) Formatting the value programmatically.

HideSelectionChanged (inherited from TextBoxBase)

Occurs when the value of the HideSelection property has changed.

MarginsChanged (inherited from C1TextBox)

Occurs when the Margins property or one of the margins has changed.

ModifiedChanged (inherited from TextBoxBase)

Occurs when the value of the Modified property has changed.

Parsed (inherited from C1TextBox) Occurs after the input string value has been converted to the DataType.

Parsing (inherited from C1TextBox) Programmatic parsing of the input string.

PostValidated (inherited from C1TextBox) Occurs after the typed value has been validated.

PostValidating (inherited from C1TextBox) Programmatic typed value validation.

PreValidated (inherited from C1TextBox) Occurs after the input string value has been validated.

PreValidating (inherited from C1TextBox) Programmatic input string validation.

ReadOnlyChanged (inherited from TextBoxBase)

Occurs when the value of the ReadOnly property has changed.

TextAlignChanged (inherited from TextBox) Occurs when the value of the TextAlign property has changed.

ModalButtonClick (inherited from C1DropDownControl)

Occurs when the Modal button is clicked.

UpDownButtonClick (inherited from C1DropDownControl)

Occurs when UpDown buttons are clicked.

ValidationError (inherited from C1TextBox) Error occurred while parsing or validating the input string.

ValueChanged (inherited from C1TextBox) Occurs when the Value changes.

VerticalAlignChanged (inherited from C1TextBox)

Occurs when the value of the VerticalAlign property has changed.


C1DateEdit Control Properties

Calendar Property The dropdown calendar object.

Syntax

[VB]

Public ReadOnly Property Calendar As DateEditMonthCalendar

[C#]

public DateEditMonthCalendar Calendar {get;}

[Delphi]

property Calandar: DateEditMonthCalandar;

See Also


C1NumericEdit Control Displays and edits numeric values. Includes a dropdown calculator for easy input of numeric values.

System.Object System.MarshalByRefObject System.ComponentModel.Component System.Windows.Forms.Control System.Windows.Forms.TextBoxBase System.Windows.Forms.TextBox C1.Win.C1Input.C1TextBox C1.Win.C1Input.C1DropDownControl C1.Win.C1Input.C1NumericEdit

C1NumericEdit Members C1NumericEdit Properties

AcceptsEscape (inherited from C1TextBox) Indicates if the Escape key that cancels modified value is handled by the control without passing it to the owner form (AcceptsEscape=True), or if it is then passed to the form so it can be closed if the form has CancelButton (AcceptsEscape=False).

AcceptsTab (inherited from C1TextBox) If True, Tab and Shift+Tab keys move the focused position within the edit mask or in DateTimeInput mode between groups of input characters.


C1NumericEdit Control · 93







AllowDbNull (inherited from C1TextBox) Determines whether it is possible to enter DBNull value in the control.



AutoSize (inherited from TextBoxBase) Gets or sets a value indicating whether the height of the control automatically adjusts when the font assigned to the control is changed.







ButtonCursor (inherited from C1DropDownControl)

The cursor that is displayed when the mouse is over a button.

Calculator Represents the class of dropdown calculator.






CaseSensitive (inherited from C1TextBox) True if string comparisons are case-sensitive; otherwise, False.








CopyWithLiterals (inherited from Control) Used with numeric input mode and edit mask. If True, text in the clipboard includes literals.


Culture (inherited from C1TextBox) The culture ID.

CultureInfo (inherited from C1TextBox) The current CultureInfo object.

CultureName (inherited from C1TextBox) The name selected for the Culture property in the Properties grid.


CustomFormat (inherited from C1TextBox) Custom format specifier used if FormatType = FormatTypeEnum.CustomFormat.


DataField (inherited from C1TextBox) The field of the data source object to which the control is bound.

DataSource (inherited from C1TextBox) The data source object to which the control is bound.

DataType (inherited from C1TextBox) Type of the Value property.


DisplayFormat (inherited from C1TextBox) Format used to display the value when the control is not in edit mode.





DropDownFormAlign (inherited from C1DropDownControl)

Alignment of the dropdown relative to the control.

DroppedDown (inherited from C1DropDownControl)

Run-time read-only property indicating if the dropdown is currently open.

EditFormat (inherited from C1TextBox) Format used to display the value when the control is in edit mode (has input focus and is not read-only).

EditMask (inherited from C1TextBox) The edit mask string restricting user input.

EditMode (inherited from C1TextBox) Returns True, if the control has input focus and TextDetached = False.

EmptyAsNull (inherited from C1TextBox) If True, empty strings are interpreted as null values (DBNull).


ErrorInfo (inherited from C1TextBox) Settings affecting error handling in the control.




FormatType (inherited from C1TextBox) Enumeration value determining the formatting method, including standard .NET format specifiers, custom and programmatic formatting.

GapHeight (inherited from C1DropDownControl)

Distance in pixels between the control edge and the dropdown.






Increment Indicates the amount to increment/decrement when the user clicks up/down buttons.


InitialSelection (inherited from C1TextBox) Determines the selection position when a control receives input focus.

InterceptArrowKeys (inherited from C1DropDownControl)

Determines if the up/down buttons intercept and handle Up and Down arrow keys.





Label (inherited from C1TextBox) Label control associated with this input field.



Margins (inherited from C1TextBox) The spacing between the input control content and its edges, in pixels.

MaskInfo (inherited from C1TextBox) Edit mask settings.


Modified (inherited from C1TextBox) Gets or sets a value that indicates that the control has been modified by the user since the control received the input focus or its Value last set.


NullText (inherited from C1TextBox) String representing a DBNull value.

NumericInput (inherited from C1TextBox) Sets or gets a value indicating whether a special edit mode is used for numeric values.

NumericInputKeys (inherited from C1TextBox)

Enables/disables the special keys used when NumericInput = True.


ParseInfo (inherited from C1TextBox) Settings affecting parsing, that is, converting the string entered by the user to the data type.

PostValidation (inherited from C1TextBox) Validation rules applied after parsing, that is, after converting the string entered by the user to the DataType (typed validation).




PreValidation (inherited from C1TextBox) Validation rules applied before parsing, that is, before converting the string entered by the user to the DataType (raw string validation).












ShowDropDownButton (inherited from C1DropDownControl)

Determines if the dropdown button is visible.

ShowModalButton (inherited from C1DropDownControl)

Determines if the modal button is visible.

ShowUpDownButtons (inherited from C1DropDownControl)

Determines if the up/down buttons are visible.






Text (inherited from C1TextBox) The current text in the control.






TrimEnd (inherited from C1TextBox) If True, trailing spaces are removed.

TrimStart (inherited from C1TextBox) If True, leading spaces are removed.

UserCultureOverride (inherited from C1TextBox)

If True, current user regional settings override the selected culture.

Value (inherited from C1TextBox) The main bindable property of a C1Input control.

ValueIsDbNull (inherited from C1TextBox) Gets or sets a value indicating whether the Value is DBNull.

VerticalAlign (inherited from C1TextBox) Vertical alignment of the contents in the control.


VisibleButtons (inherited from C1DropDownControl)

Enumeration specifying which buttons are visible.


C1NumericEdit Methods




CheckValidationResult (inherited from C1TextBox)

Checks the result of the ParseContent method.



CloseDropDown (inherited from C1DropDownControl)

Closes the dropdown.



OpenDropDown (inherited from C1DropDownControl)

Shows the dropdown.

ParseContent (inherited from C1TextBox) Parses the Text string.
















ResetText (inherited from C1TextBox) Updates the control's Text with the current Value.










SetProposedValue (inherited from C1TextBox)

Works exactly as setting the Value property, except that it does not change the internal variable storing the value before editing, so the user can press Esc and restore the previous value.



SuspendNumericInput (inherited from C1TextBox)

Temporarily disables numeric input mode (see NumericInput property).




UpdateValueWithCurrentText (inherited from C1TextBox)

Triggers parsing of the Text property and updating the Value.

C1NumericEdit Events (events inherited from Control are not shown)





ButtonCursorChanged (inherited from C1DropDownControl)

Occurs when the ButtonCursor property changes.


ContextMenuChanged (inherited from Control)

Occurs when the value of the ContextMenu property changes.

CultureInfoSetup (inherited from C1TextBox)

CultureInfo can be set up (on startup) or has been changed.

DataTypeChanged (inherited from C1TextBox)

Occurs when the DataType property changes.

DropDownFormAlignChanged (inherited from C1DropDownControl)

Occurs when the value of the DropDownFormAlign property has changed.

DropDownClosed (inherited from C1DropDownControl)

Occurs when the dropdown has been closed.


DropDownOpened (inherited from C1DropDownControl)

Occurs before the dropdown is opened.

FormatError (inherited from C1TextBox) Occurs when the control receives data that cannot be formatted according to the current format and edit mask settings.

Formatted (inherited from C1TextBox) Occurs after the value has been formatted.

Formatting (inherited from C1TextBox) Formatting the value programmatically.



MarginsChanged (inherited from C1TextBox)

Occurs when the Margins property or one of the margins has changed.



Parsed (inherited from C1TextBox) Occurs after the input string value has been converted to the DataType.

Parsing (inherited from C1TextBox) Programmatic parsing of the input string.

PostValidated (inherited from C1TextBox) Occurs after the typed value has been validated.

PostValidating (inherited from C1TextBox) Programmatic typed value validation.

PreValidated (inherited from C1TextBox) Occurs after the input string value has been validated.

PreValidating (inherited from C1TextBox) Programmatic input string validation.




ModalButtonClick (inherited from C1DropDownControl)

Occurs when the Modal button is clicked.

UpDownButtonClick (inherited from C1DropDownControl)

Occurs when UpDown buttons are clicked.

ValidationError (inherited from C1TextBox) Error occurred while parsing or validating the input string.

ValueChanged (inherited from C1TextBox) Occurs when the Value changes.

VerticalAlignChanged (inherited from C1TextBox)

Occurs when the value of the VerticalAlign property has changed.

Calculator Property · 103

C1NumericEdit Control Properties

Calculator Property Represents the class of dropdown calculator.

Syntax

[VB]

Public ReadOnly Property Calculator As NumericEditCalculator

[C#]

public NumericEditCalculator Calculator {get; set;}

[Delphi]

property Calculator : NumericEditCalculator;

See Also


Increment Property Indicates the amount to increment/decrement when the user clicks up/down buttons.

Syntax

[VB]

Public Property Increment As Object

[C#]

public object Increment {get; set;}

[Delphi]

property Increment: Object;

See Also


C1DbNavigator Control Data bound control providing buttons for convenient navigation over data source rows, moving to the first, last, previous and next row and performing common data actions such as updating the data source and refreshing data. Button functions are described in NavigatorButtonFlags.

System.Object System.MarshalByRefObject System.ComponentModel.Component System.Windows.Forms.Control System.Windows.Forms.ScrollableControl System.Windows.Forms.ContainerControl System.Windows.Forms.UserControl C1.Win.C1Input.C1DbNavigator


C1DbNavigator Members C1DbNavigator Properties








ActiveControl (inherited from ContainerControl)

Gets or sets the active control on the container control.



BackColor (inherited from Control) Gets or sets the background color for the control.



BorderStyle Navigator border style.



ButtonCursor The cursor that is displayed when the mouse is over a button.

ButtonSize The size of navigator buttons.

ButtonStyle Navigator button style.

ButtonTextAlign Controls how the text is positioned relative to the image in navigator buttons.

ButtonTexts Gets or sets the texts displayed on the buttons.

ButtonTooltips The string collection defining navigator button tooltips.

C1DbNavigator Control · 105




CausesFormValidation Whether the control in focus should be validated before a button click is handled by the navigator.

CausesValidation (inherited from Control) Gets or sets a value indicating whether the control causes validation (i.e. calls Validating and Validated events).



ColorButtons Specifies if navigator buttons have color bitmaps.

ColorWhenHover If True, navigator buttons show color bitmaps when the mouse hovers over them.


ConfirmDelete Whether a confirmation dialog is shown before deleting a record.






CurrencyManager Gets or sets the CurrencyManager object navigated by the control.



DataMember For multi-table data sources, specifies a specific table to which the control is bound.

DataSource The data source object to which the control is bound.





DockPadding (inherited from ScrollableControl)

Gets the dock padding settings for all edges of the control.


EnabledButtons Flags enumeration specifying which buttons are enabled.

ErrorProvider Gets or sets an ErrorProvider object used to indicate error state of the current data row.



ForeColor Foreground color for caption texts and button borders.




HorizontalIndent Horizontal margin between the border and the buttons.

ImageList Gets or sets the ImageList to use when displaying button images without highlighting.

ImageListHighlight Gets or sets the ImageList to use when displaying button images in highlighted state.









MoveDelayFirst Time delay in milliseconds after pressing Next/Previous button before automatic scrolling begins.

MoveDelayNext Time delay in milliseconds between row moves in automatic scrolling.



ParentForm (inherited from ContainerControl)

Gets the form that the container control is assigned to.

PageSize Number of rows to skip when the user presses PageUp/Down

Position Gets or sets the current row position in the table (from 0 to RowCount - 1).

PositionVisible Specifies whether the editable row position field and row captions are visible in the navigator.






RowCount Returns the number of rows in the table.

ShowToolTips Indicates whether tooltips are shown for the buttons.







Text (inherited from Control) Gets or sets the text associated with this control.



UIStrings The string collection defining navigator caption texts.

VerticalAlign Vertical alignment of navigator buttons.

VerticalIndent Vertical margin between the border and the buttons.


VisibleButtons Flags enumeration specifying which buttons are visible.


C1DbNavigator Methods



ClickButton Performs the action associated with a navigator button.

















ResetText (inherited from Control) Resets the Text property to its default value.



Select (inherited from Control) Activates a control.




SetDataBinding Sets the DataSource and DataMember properties at run time.





Validate (inherited from ContainerControl) Validates the last invalidated control and its ancestors up through, but not including, the current control.

BorderStyle Property (C1DbNavigator) · 111

C1DbNavigator Events (events inherited from Control are not shown)

BeforeAction Occurs when a button is clicked, before the action is executed.

ButtonClick Occurs when a navigator button has been pressed, after the button action is performed.

ButtonCursorChanged Occurs when the ButtonCursor property changes.

Disposed (inherited from Component) Adds an event handler to listen to the Disposed event on the component.

Editing Occurs when the Edit button is pressed.

Error Occurs when an exceptions is thrown performing an action on button click.

ItemChanged Occurs when the current row has been modified, some of its fields changed.

PositionChanged Occurs when the Position has changed.

RefreshData Occurs when the Refresh button is pressed.

UpdateData Occurs when the Update button is pressed.

C1DbNavigator Control Properties

BorderStyle Property (C1DbNavigator) Navigator border style.

Syntax

[VB]

Public Property BorderStyle As BorderStyle

[C#]

public BorderStyle BorderStyle {get; set;}

[Delphi]

property BorderStyle: BorderStyle;

See Also

C1DbNavigator Control (page 103)

ButtonCursor Property The cursor that is displayed when the mouse is over a button.

Syntax

[VB]

Public Property ButtonCursor As Cursor


[C#]

public Cursor ButtonCursor { get; set; }

[Delphi]

property ButtonCursor: Cursor;

Remarks

This property is useful when you set the control's Cursor property and want the cursor to have a different shape when the mouse is over a button.

See Also





ButtonSize Property The size of navigator buttons.

Syntax

[VB]

Public Property ButtonSize As Size

[C#]

public Size ButtonSize {get; set;}

[Delphi]

property ButtonSize: Size;

Remarks

This property has effect only if ButtonStyle = Standard. If ButtonStyle = Flat, this property is ignored and button size is always determined automatically.

See Also


ButtonStyle Property Navigator button style.

Syntax

[VB]

Public Property ButtonStyle As NavigatorButtonStyleEnum

[C#]

public NavigatorButtonStyleEnum ButtonStyle {get; set;}

ButtonTextAlign Property · 113

[Delphi]

property ButtonStyle : NavigatorButtonStyleEnum;

See Also


ButtonTextAlign Property Controls how the text is positioned relative to the image in navigator buttons.

Syntax

[VB]

Public Property ButtonTextAlign As NavigatorButtonTextAlignEnum

[C#]

public NavigatorButtonTextAlignEnum ButtonTextAlign {get; set;}

[Delphi]

property ButtonTextAlign: NavigatorButtonTextAlignEnum;

See Also


ButtonTexts Property Gets or sets the texts displayed on the buttons.

Syntax

[VB]

Public ReadOnly Property ButtonTexts As UIStrings

[C#]

public UIStrings ButtonTexts {get;}

[Delphi]

property ButtonTexts: UIStrings;

Remarks

All button text strings are empty by default, only images appear on the buttons.

See Also


ButtonToolTips Property The string collection defining navigator button tooltips.

Syntax

[VB]

Public ReadOnly Property ButtonToolTips As UIStrings


[C#]

public UIStrings ButtonToolTips {get;}

[Delphi]

property ButtonToolTips: UIStrings;

Remarks

Use this property to customize or localize the strings shown as button tooltips.

See Also


CausesFormValidation Property Whether the control in focus should be validated before a button click is handled by the navigator.

Syntax

[VB]

Public Property CausesFormValidation As Boolean

[C#]

public bool CausesFormValidation {get; set;}

[Delphi]

property CausesFormValidation: Boolean;

See Also


ColorButtons Property Specifies if navigator buttons have color bitmaps.

Syntax

[VB]

Public Property ColorButtons As Boolean

[C#]

public bool ColorButtons {get; set;}

[Delphi]

property ColorButtons: Boolean;

Remarks

If True (default), buttons Add, Delete, Update, Refresh have color bitmaps, otherwise, black/white.

See Also


ColorWhenHover Property · 115

ColorWhenHover Property If True, navigator buttons show color bitmaps when the mouse hovers over them.

Syntax

[VB]

Public Property ColorWhenHover As Boolean

[C#]

public bool ColorWhenHover {get; set;}

[Delphi]

property ColorWhenHover: Boolean;

See Also


ConfirmDelete Property Whether a confirmation dialog is shown before deleting a row.

Syntax

[VB]

Public Property ConfirmDelete As Boolean

[C#]

public bool ConfirmDelete {get; set;}

[Delphi]

property ConfirmDelete: Boolean;

Remarks

Default: True.

See Also


CurrencyManager Property Gets or sets the CurrencyManager object navigated by the control.

Syntax

[VB]

Public Property CurrencyManager As CurrencyManager

[C#]

public CurrencyManager CurrencyManager {get; set;}

[Delphi]

property CurrencyManager: CurrencyManager;


Remarks

This property is available only at run time and can be set, for example, to a CurrencyManager of another form.

See Also


DataMember Property For multi-table data sources, specifies a specific table to which the control is bound.

Syntax

[VB]

Public Property DataMember As String

[C#]

public string DataMember {get; set;}

[Delphi]

property DataMember: string;

Remarks

Related Topic: DataSource

See Also


DataSource Property (C1DbNavigator) The data source object to which the control is bound.

Syntax

[VB]

Public Property DataSource As Object

[C#]

public object DataSource {get; set;}

[Delphi]

property DataSource: Object;

Remarks

For multi-table data sources, the control binds to a table, not to the whole data set. In this case, the DataSource property is used together with the DataMember property that specifies a table in the multi-table data source.

See Also


EnabledButtons Property · 117

EnabledButtons Property Flags enumeration specifying which buttons are enabled.

Syntax

[VB]

Public Property EnabledButtons As NavigatorButtonFlags

[C#]

public NavigatorButtonFlags EnabledButtons {get; set;}

[Delphi]

property EnabledButtons: NavigatorFlagButtons;

Remarks

Default: all visible buttons are enabled.

See Also


ErrorProvider Property (C1DbNavigator) Gets or sets an ErrorProvider object used to indicate error state of the current data row.

Syntax

[VB]

Public Property ErrorProvider As ErrorProvider

[C#]

public ErrorProvider ErrorProvider {get; set;}

[Delphi]

property ErrorProvider: ErrorProvider;

Remarks

If this property is set, and current row has an error (RowError property is set in ADO.NET or C1DataObjects), the navigator control indicates the error using the icon defined in the specified error provider.

See Also


ForeColor Property Foreground color for caption texts and button borders.

Syntax

[VB]

Public Property ForeColor As Color


[C#]

public Color ForeColor {get; set;}

[Delphi]

property ForeColor: Color;

See Also


HorizontalIndent Property Horizontal margin between the border and the buttons.

Syntax

[VB]

Public Property HorizontalIndent As Integer

[C#]

public int HorizontalIndent {get; set;}

[Delphi]

property HorizontalIndent: Integer;

Remarks

All contents of a navigator control appear inside the margins, including the buttons and the "Row:" text.

See Also


ImageList Property Gets or sets the ImageList to use when displaying button images without highlighting.

Syntax

[VB]

Public Property ImageList As ImageList

[C#]

public ImageList ImageList {get; set;}

[Delphi]

property ImageList: ImageList;

Remarks

This property specifies the images shown on the buttons when they are not in highlighted state (ColorButtons = False and the mouse is not over the button, if ColorWhenHover = True).

If this property is set to null (default), default images are used.

Related topics

ImageListHighlight

ImageListHighlight Property · 119

See Also


ImageListHighlight Property Gets or sets the ImageList to use when displaying button images in highlighted state.

Syntax

[VB]

Public Property ImageListHighlight As ImageList

[C#]

public ImageList ImageListHighlight {get; set;}

[Delphi]

property ImageListHighlight: ImageList;

Remarks

This property specifies the images shown on the buttons when they are in highlighted state (ColorButtons = True or the mouse is over the button and ColorWhenHover = True).

If this property is set to null (default), the ImageList property is used.

See Also


MoveDelayFirst Property Time delay in milliseconds after pressing Next/Previous button before automatic scrolling begins.

Syntax

[VB]

Public Property MoveDelayFirst As Integer

[C#]

public int MoveDelayFirst {get; set;}

[Delphi]

property MoveDelayFirst: Integer;

Remarks

Default: 600 ms.

See Also



MoveDelayNext Property Time delay in milliseconds between row moves in automatic scrolling.

Syntax

[VB]

Public Property MoveDelayNext As Integer

[C#]

public int MoveDelayNext {get; set;}

[Delphi]

property MoveDelayNext: Integer;

Remarks

Default: 300 ms.

See Also


PageSize Property Number of rows to skip when the user presses PageUp/Down.

Syntax

[VB]

Public Property PageSize As Integer

[C#]

public int PageSize {get; set;}

[Delphi]

property PageSize: Integer;

Remarks

Default: 10.

See Also


Position Property Gets or sets the current row position in the table (from 0 to RowCount - 1).

Syntax

[VB]

Public Property Position As Integer

[C#]

public int Position {get; set;}

PositionVisible Property · 121

[Delphi]

property Position: Integer;

See Also


PositionVisible Property Specifies whether the editable row position field and row captions are visible in the navigator.

Syntax

[VB]

Public Property PositionVisible As Boolean

[C#]

public bool PositionVisible {get; set;}

[Delphi]

property PositionVisible: Boolean;

Remarks

Default: True.

See Also


RowCount Property Returns the number of rows in the table.

Syntax

[VB]

Public ReadOnly Property RowCount As Integer

[C#]

public int RowCount {get;}

[Delphi]

property RowCount: Integer;

See Also


ShowToolTips Property Indicates whether tooltips are shown for the buttons.

Syntax

[VB]

Public Property ShowToolTips As Boolean


[C#]

public bool ShowToolTips {get; set;}

[Delphi]

property ShowToolTips: Boolean;

See Also


UIStrings Property (C1DbNavigator) The string collection defining navigator caption texts.

Syntax

[VB]

Public Property UIStrings As UIStrings

[C#]

public UIStrings UIStrings {get; set;}

[Delphi]

property UIStrings: UIStrings;

Remarks

Use this property to customize or localize the strings shown in the control.

See Also


VerticalAlign Property Vertical alignment of navigator buttons.

Syntax

[VB]

Public Property VerticalAlign As NavigatorVerticalAlignEnum

[C#]

public NavigatorVerticalAlignEnum VerticalAlign {get; set;}

[Delphi]

property VerticalAlign: NavigatorVerticalAlignEnum;

See Also


VerticalIndent Property · 123

VerticalIndent Property Vertical margin between the border and the buttons.

Syntax

[VB]

Public Property VerticalIndent As Integer

[C#]

public int VerticalIndent {get; set;}

[Delphi]

property VerticalIndent: Integer;

Remarks

Buttons are indented from the top, bottom or center, according to the value of the VerticalAlign property.

See Also


VisibleButtons Property (C1DbNavigator) Flags enumeration specifying which buttons are visible.

Syntax

[VB]

Public Property VisibleButtons As NavigatorButtonFlags

[C#]

public NavigatorButtonFlags VisibleButtons {get; set;}

[Delphi]

property VisibleButtons: NavigatorButtonFlags;

Remarks

Default: Navigation (Next, Previous, First, Last).

See Also


C1DbNavigator Control Methods

ClickButton Method Performs the action associated with a navigator button.

Syntax

[VB]

Public Function ClickButton (button As NavigatorButtonEnum)


[C#]

public void ClickButton (NavigatorButtonEnum button)

[Delphi]

procedure ClickButton (button: NavigatorButtonEnum);

Parameter Description

NavigatorButtonEnum button

The button whose action is performed.

Remarks

This method performs the exact action as would be triggered by pressing a button. If the button is disabled, the method does nothing.

See Also


SetDataBinding Method Sets the DataSource and DataMember properties at run time.

Syntax

[VB]

Public Sub SetDataBinding(dataSource As Object, dataMember As String)

[C#]

public void SetDataBinding(object dataSource, string dataMember)

[Delphi]

procedure SetDataBinding (datasource: Object; datamember: string);


Object dataSource The data source object to which the control is bound.

String dataMember For multi-table data sources, specifies a specific table to which the control is bound.

See Also


BeforeAction Event · 125

C1DbNavigator Control Events

BeforeAction Event Occurs when a button is clicked, before the action is executed.

Syntax

[VB]

Public Event BeforeAction As NavigatorBeforeActionEventHandler

[C#]

public event NavigatorBeforeActionEventHandler BeforeAction

[Delphi]

property BeforeAction: NavigatorBeforeActionEventHandler;

Remarks

You can make the navigator control skip the standard action associated with the button by setting the Cancel argument to True in your event handler code.

See Also


ButtonCursorChanged Event Occurs when the ButtonCursor property changes.

Syntax

[VB]

Public Event ButtonCursorChanged As EventHandler

[C#]

public event EventHandler ButtonCursorChanged

[Delphi]

property ButtonCursorChanged: EventHandler

See Also






ButtonClick Event Occurs when a navigator button has been pressed, after the button action is performed.

Syntax

[VB]

Public Event ButtonClick As NavigatorButtonClickEventHandler

[C#]

public event NavigatorButtonClickEventHandler ButtonClick

[Delphi]

property ButtonClick: NavigatorButtonClickEventHandler;

See Also


Editing Event Occurs when the Edit button is pressed.

Syntax

[VB]

Public Event Editing As NavigatorEditingEventHandler

[C#]

public event NavigatorEditingEventHandler Editing

[Delphi]

property Editing: NavigatorEditingEventHandler;

Remarks

The Edit button does not have built-in functionality, because different data sources and different applications may require different actions to start edit mode. To implement Edit button functionality, write code in this event. You can put any code here, but the intent is to starts editing the current row, put it in edit mode.

See Also


Error Event Occurs when exception is thrown performing an action on button click.

Syntax

[VB]

Public Event Error As NavigatorErrorEventHandler

[C#]

public event NavigatorErrorEventHandler Error

ItemChanged Event · 127

[Delphi]

property Error: NavigatorErrorEventHandler;

Remarks

If the programmer does not handle the exception in the Error event, C1DbNavigator shows standard message box and the exception is considered handled, does not propagate further. The programmer can show a custom message box or handle the exception in another way in the Error event code and set the ShowErrorMessage event argument to False to suppress the standard message box. It is also possible to set the ErrorMessage and ErrorMessageCaption event arguments to change the standard error message box. The programmers can also throw an exception in the Error event if they want the exception to propagate beyond C1DbNavigator.

See Also


ItemChanged Event Occurs when the current row has been modified, some of its fields changed.

Syntax

[VB]

Public Event ItemChanged As ItemChangedEventHandler

[C#]

public event ItemChangedEventHandler ItemChanged

[Delphi]

property ItemChanged: ItemChangedEventHandler;

Remarks

This event is triggered by the CurrencyManager.ItemChanged event.

See Also


PositionChanged Event Occurs when the Position has changed.

Syntax

[VB]

Public Event PositionChanged As EventHandler

[C#]

public event EventHandler PositionChanged

[Delphi]

property PositionChanged: EventHandler;

Remarks

This event is triggered by the CurrencyManager.ItemChanged event.


See Also


RefreshData Event Occurs when the Refresh button is pressed.

Syntax

[VB]

Public Event RefreshData As EventHandler

[C#]

public event EventHandler RefreshData

[Delphi]

property RefreshData: EventHandler;

Remarks

The Refresh button does not have built-in functionality, because different data sources require different actions for refresh. To implement Refresh button functionality, write code in this event. You can put any code in that event, but the intent is to re-fetch your data from the database (canceling all modifications done by the user). Before firing the RefreshData event, C1Dbnavigator calls CurrencyManager.CancelCurrentEdit. After the RefreshData event, it calls CurrencyManager.Refresh.

See Also


UpdateData Event Occurs when the Update button is pressed.

Syntax

[VB]

Public Event UpdateData As EventHandler

[C#]

public event EventHandler UpdateData

[Delphi]

property UpdateData: EventHandler;

Remarks

The Update button does not have built-in functionality, because different data sources require different actions for update. To implement Update button functionality, write code in this event. You can put any code here, but the intent is to update the database, send the modifications to the database. Before firing the UpdateData event, C1DbNavigator calls CurrencyManager.EndCurrentEdit.

See Also


C1Label Control · 129

C1Label Control Read-only data bound control displaying formatted data. C1Label supports all formatting features of the C1TextBox control.

System.Object System.MarshalByRefObject System.ComponentModel.Component System.Windows.Forms.Control System.Windows.Forms.Label C1.Win.C1Input.C1Label

C1Label Members C1Label Properties










AutoSize (inherited from Label) Gets or sets a value indicating whether the control is automatically resized to display its entire contents.


BackgroundImage (inherited from Label) See Control.BackgroundImage.


BorderStyle (inherited from Label) Gets or sets the border style for the control.







CaseSensitive True if string comparisons are case-sensitive; otherwise, False.









Culture The culture ID.

CultureInfo The current CultureInfo object.

CultureName The name selected for the Culture property in the Properties grid.

CurrentTimeZone If True, the control’s stored Value is in current time zone; otherwise, the Value is adjusted to the time zone defined by the GMTOffset property.


CustomFormat Custom format specifier used if FormatType = FormatTypeEnum.CustomFormat.


DataField The field of the data source object to which the control is bound.


DataType Type of the Value property.






EmptyAsNull If True, empty strings are interpreted as null values (DBNull).





ForeColor (inherited from Control) Gets or sets the foreground color of the control.

FormatInfo Format used to display the value.

FormatType Enumeration value determining the formatting method, including standard .NET format specifiers, custom and programmatic formatting.

GMTOffset The time zone of the Value property used if CurrentTimeZone = False.




Image (inherited from Label) Gets or sets the image that is displayed on a Label.

ImageAlign (inherited from Label) Gets or sets the alignment of an image that is displayed in the control.

ImageIndex (inherited from Label) Gets or sets the index value of the image displayed on the Label.

ImageList (inherited from Label) Gets or sets the ImageList that contains the images to display in the Label control.

ImeMode (inherited from Label) Gets or sets the Input Method Editor(IME) mode supported by this control.








MaskInfo Edit mask settings.


NullText String representing a DBNull value.














Text The current text in the control.

TextDetached Specifies whether the Value and Text properties can be set independently.



TrimEnd If True, trailing spaces are removed.

TrimStart If True, leading spaces are removed.

UseMnemonic (inherited from Label) Gets or sets a value indicating whether the control interprets an ampersand character (&) in the control's Text property to be an access key prefix character.

UserCultureOverride If True, current user regional settings override the selected culture.

Value The main bindable property of a C1Input control.

ValueIsDbNull Gets or sets a value indicating whether the Value is DBNull.



C1Label Methods


















ResetText Updates the control's Text with the current Value.











C1Label Events (events inherited from Control are not shown)

AutoSizeChanged (inherited from Label) Occurs when the value of the AutoSize property has changed.

CultureInfoSetup CultureInfo can be set up (on startup) or has been changed.

DataTypeChanged Occurs when the DataType property changes.

Formatted Occurs after the value has been formatted.


Formatting Formatting the value programmatically.

TextAlignChanged (inherited from Label) Occurs when the value of the TextAlign property has changed.

ValueChanged Occurs when the Value changes.

C1Label Properties For the full list of C1Label properties, methods and events, see C1Label Members (page 129.)

ErrorProvider Property (C1Label) Gets or sets an ErrorProvider object used to indicate error state of the control.

Syntax

[VB]


[C#]


[Delphi]

property ErrorProvider: ErrorProvider;

Remarks

If this property is set, the specified error provider is used to signal error conditions occurring in the control (ErrorProvider.SetControl method is used to show errors in the error provider). Following error conditions are shown:

• Value obtained from the database does not conform to the edit mask.

• An exception occurs formatting the value obtained from the database.

• Formatting the text obtained from the database is done in the Formatting event, and fails (Formatting event returns Succeeded = False).

See Also

C1Label Control (page 129)

ErrorInfo Class (page 272)

FormatInfo Property Format used to display the value.

Syntax

[VB]

Public ReadOnly Property FormatInfo As FormatInfo

[C#]

public FormatInfo FormatInfo {get;}

C1PictureBox Control · 137

[Delphi]

property FormatInfo: FormatInfo;

Remarks

Related Topic: DisplayFormat

See Also


C1PictureBox Control In addition to the standard PictureBox functionality, C1PictureBox supports data binding to data source fields containing image data. To bind to a binary field containing image data, use DataSource and DataField properties.

System.Object System.MarshalByRefObject System.ComponentModel.Component System.Windows.Forms.Control System.Windows.Forms.PictureBox C1.Win.C1Input.C1PictureBox

C1PictureBox Members C1PictureBox Properties












BorderStyle (inherited from PictureBox) Indicates the border style for the control.

C1PictureBox Control· 139





Image (inherited from PictureBox) Gets or sets the image that the control displays.

ImeMode (inherited from PictureBox) Gets or sets the Input Method Editor (IME) mode of the control.

ImmediateUpdate Specifies whether the image should be put into the data source right after the Image property has been changed.

















SizeMode (inherited from PictureBox) Indicates how the image is displayed.






C1PictureBox Methods



CopyImage Copies the image currently in the control to the clipboard.












C1PictureBox Control· 141









ImageFromByteArray Converts a byte array to an image.

ImageToByteArray Returns the contents of an image.





PasteImage If the clipboard contains an image, this method replaces the contents of the Image property of the control with that image.
















ResetText (inherited from Control) Resets the Text property to its default value.











C1PictureBox Events (events inherited from PictureBox are not shown)

BindingFormatting Occurs when Image is retrieved from the data source.

BindingParsing Occurs when Image is stored in the data source.

ImageChanged Occurs when the Image property changes

ImmediateUpdate Property· 143

C1PictureBox Control Properties

ImmediateUpdate Property Specifies whether the image should be put into the data source right after the Image property has been changed.

Syntax

[VB]

Public Property ImmediateUpdate As Boolean

[C#]

public bool ImmediateUpdate { get; set; }

[Delphi]

property ImmediateUpdate: Boolean;

Remarks

Default: False.

If it is False (default option) the image shouldn't be put in data source until the following call of the CurrencyManager.EndCurrentEdit() method.

See Also

C1PictureBox Control (page 137)

C1PictureBox Control Methods

CopyImage Method Copies the image currently in the control to the clipboard.

Syntax

[VB]

Public Sub CopyImage()

[C#]

public void CopyImage()

[Delphi]

procedure CopyImage();

Remarks

If the Image property is DBNull, this method does nothing.

See Also



ImageFromByteArray Method Converts a byte array to an image.

Syntax

[VB]

Public Shared Function ImageFromByteArray(buffer As Byte()) As Image

[C#]

public static Image ImageFromByteArray ( byte[] buffer )

[Delphi]

function ImageFromByteArray (buffer: Byte): Image;


byte[] buffer The contents of an image. To put the resulting image into a C1PictureBox control, set the C1PictureBox.Image property to the result of this method.

See Also


ImageToByteArray Method Returns the contents of an image.

Syntax

[VB]

Public Shared Function ImageToByteArray(image As Image, format As ImageFormat) As Byte()

[C#]

public static byte[] ImageToByteArray(Image image, ImageFormat format)

[Delphi]

function ImageToByteArray (image: Image; format: ImageFormat): Byte;


System.Drawing.Image image Image to return as a byte array. To return the image currently in the C1PictureBox control, use the C1PictureBox.Image property.

System.Drawing.Imaging.ImageFormat format

Format in which to return the image contents.

See Also


PasteImage Method· 145

PasteImage Method If the clipboard contains an image, this method replaces the contents of the Image property of the control

Syntax

[VB]

Public Sub PasteImage()

[C#]

public void PasteImage()

[Delphi]

procedure PasteImage();

See Also


C1PictureBox Control Events

ImageChanged Event Occurs when the Image property changes

Syntax

[VB]

Public Event ImageChanged As EventHandler

[C#]

public event System.EventHandler ImageChanged

[Delphi]

property ImageChanged: EventHandler;

See Also


C1TextBox Control The main data bound control used for entering and editing information in a text form. Supports data formatting for all data types, including special features for date-time formats. Also supports edit mask, data validation and other features.

System.Object System.MarshalByRefObject System.ComponentModel.Component System.Windows.Forms.Control System.Windows.Forms.TextBoxBase System.Windows.Forms.TextBox C1.Win.C1Input.C1TextBox C1.Win.C1Input.C1DropDownControl C1.Win.C1Input.C1DateEdit C1.Win.C1Input.C1NumericEdit


C1TextBox Members C1TextBox Properties

AcceptsEscape (inherited from C1TextBox) Indicates if the Escape key that cancels modified value is handled by the control without passing it to the owner form (AcceptsEscape=True), or if it is then passed to the form so it can be closed if the form has a CancelButton (AcceptsEscape=False).

AcceptsReturn (inherited from TextBox) Gets or sets a value indicating whether pressing ENTER in a multiline TextBox control creates a new line of text in the control or activates the default button for the form.

AcceptsTab (inherited from TextBoxBase) In C1TextBox, this property now works differently from the standard TextBox.AcceptsTab (which only applies to a multiline text box). If AcceptsTab = True, Tab and Shift+Tab keys move the focused position within the edit mask or in DateTimeInput mode between groups of input characters. When the last group is reached, the following Tab moves the input focus to the next control in the tab order.








AllowDbNull Determines whether it is possible to enter DBNull value in the control.



AutoChangePosition Gets or sets a value indicating whether the position of the character is automatically changed.

AutoSize (inherited from TextBoxBase) Gets or sets a value indicating whether the height of the control automatically adjusts

C1TextBox Control· 147

when the font assigned to the control is changed.












CausesValidation (inherited from Control) Gets or sets a value indicating whether the control causes validation (i.e. calls Validated and Validating events).

CharacterCasing (inherited from TextBox) Gets or sets whether the TextBox control modifies the case of characters as they are typed.









CopyWithLiterals Used with numeric input mode and edit mask. If True, text in the clipboard includes literals.


Culture The culture ID.

CultureInfo The current CultureInfo object.

CultureName The name selected for the Culture property in the Properties grid.

CurrentTimeZone If True, the control’s stored Value is in current time zone; otherwise, the Value is adjusted to the time zone defined by the GMTOffset property.






DataType Type of the Value property.

DateTimeInput Whether or not a special edit mode is applied to DateTime values.


DisableOnNoData Gets or sets whether the text box should be disabled when it is bound to an empty data source.

DisplayFormat Format used to display the value when the control is not in edit mode.




EditFormat Format used to display the value when the control is in edit mode (has input focus and is not read-only).


EditMask The edit mask string restricting user input.

EditMode Returns True, if the control has input focus and TextDetached = False.



ErrorInfo Settings affecting error handling in the control.





GMTOffset The time zone of the Value property used if CurrentTimeZone = False.






InitialSelection Determines the selection position when a control receives input focus.






Label Label control associated with this input field.


Lines (inherited from TextBoxBase) The lines of text in a multiline control.


Margins The spacing between the input control content and its edges, in pixels.

MaskInfo Edit mask settings.


MinShortYear The minimum year that can be entered without leading zeros.

Modified (inherited from TextBoxBase) Gets or sets a value that indicates that the control has been modified by the user since the control received the input focus or its Value last set.

Multiline (inherited from TextBoxBase) Gets or sets a value indicating whether this is a multiline text box control.



NumericInput Sets or gets a value indicating whether a special edit mode is used for numeric values.

NumericInputKeys Enables/disables the special keys used when NumericInput = True.


ParseInfo Settings affecting parsing, that is, converting the string entered by the user to the data type.

PasswordChar (inherited from TextBox) Gets or sets the character used to mask characters of a password in a single-line TextBox control.

PostValidation Validation rules applied after parsing, that is, after converting the string entered by the user to the DataType (typed validation).



PreValidation Validation rules applied before parsing, that is, before converting the string entered by the user to the DataType (raw string validation).

ProductName (inherited from Control) Gets the product name of the assembly


containing the control.







ScrollBars (inherited from TextBox) Gets or sets which scroll bars should appear in a multiline TextBox control.





ShowContextMenu Specifies whether the context menu can be displayed for the control.

ShowFocusRectangle Specifies whether a focus rectangle should be displayed around the client area when the control has the input focus.






Text The current text in the control.


TextDetached Specifies whether the Value and Text properties can be set independently.







UserCultureOverride If True, current user regional settings override the selected culture.

Value The main bindable property of a C1Input control.

ValueIsDbNull Gets or sets a value indicating whether the Value is DBNull.

VerticalAlign Vertical alignment of the contents in the control.



WordWrap (inherited from TextBoxBase) Indicates whether a multiline text box control automatically wraps words to the beginning of the next line when necessary.

WrapDateTimeFields If this property is false, the month will be automatically incremented when the user spins the date past the end of the month.

C1TextBox Methods




CheckValidationResult Checks the result of the ParseContent method.











DecDateTimeInput Decrements the currently selected field in DateTimeInput mode.















IncDateTimeInput Decrements the currently selected field in DateTimeInput mode.






ParseContent Parses the Text string.
















ResetText (inherited from Control) Updates the control's Text with the current Value.








SetProposedValue Works exactly as setting the Value property, except that it does not change the internal variable storing the value before editing, so the user can press Esc and restore the previous value.





SuspendNumericInput Temporarily disables numeric input mode (see NumericInput property).




UpdateValueWithCurrentText Triggers parsing of the Text property and updating the Value.

C1TextBox Events (events inherited from Control are not shown)

AcceptsTabChanged (inherited from TextBoxBase)

Occurs when the value of the AcceptsTab property has changed.



BindingFormatting Occurs when Value is retrieved from the data source.

BindingParsing Occurs when Value is stored in the data source.




CultureInfoSetup CultureInfo can be set up (on startup) or has been changed.

DataTypeChanged Occurs when the DataType property changes.


FormatError Occurs when the control receives data that cannot be formatted according to the current format and edit mask settings.

Formatted Occurs after the value has been formatted.

Formatting Formatting the value programmatically.



MarginsChanged Occurs when the Margins property or one of the margins has changed.



MultilineChanged (inherited from TextBoxBase)

Occurs when the value of the Multiline property has changed.

Parsed Occurs after the input string value has been converted to the DataType.

Parsing Programmatic parsing of the input string.

PostValidated Occurs after the typed value has been validated.

PostValidating Programmatic typed value validation.

PreValidated Occurs after the input string value has been validated.

PreValidating Programmatic input string validation.




ValidationError Error occurred while parsing or validating the input string.

ValueChanged Occurs when the Value changes.

VerticalAlignChanged Occurs when the value of the VerticalAlign property has changed.

C1TextBox Control Properties

AcceptsEscape Property Indicates if the Escape key that cancels modified value is handled by the control without passing it to the owner form (AcceptsEscape=True), or if it is then passed to the form so it can be closed it the form has CancelButton (AcceptsEscape=False). Default: True.

AllowDbNull Property· 157

Syntax

[VB]

Public Property AcceptsEscape As Boolean

[C#]

public bool AcceptsEscape {get; set;}

[Delphi]

property AcceptsEscape: Boolean;

Remarks

When this property is False and the owner form has non-empty CancelButton property, pressing Escape key will reset the content of C1TextBox and, immediately after that, the form will be closed with the Cancel button. If AcceptsEscape = True and the value of the control has been changed (Modified = True), pressing Escape key will reset the value, but the owner form will stay open. If the user presses Escape second time, the form is closed.

See Also



C1TextBox Control (page 145)

AllowDbNull Property Determines whether it is possible to enter DBNull value in the control.

Syntax

[VB]

Public Property AllowDbNull As Boolean

[C#]

public bool AllowDbNull {get; set;}

[Delphi]

property AllowDbNull: Boolean;

Remarks

If the property is set to True (default), DBNull values are allowed.

This property duplicates the property with the same name in PostValidation.

See Also




PostValidation Class (page 246)


AutoChangePosition Property Gets or sets a value indicating whether the position of the character is automatically changed.

Syntax

[VB]

Public Property AutoChangePosition As Boolean

[C#]

public bool AutoChangePosition {get, set;}

[Delphi]

property AutoChangePosition: Boolean;

Remarks

If this property is False the user has to press the right arrow key or the next literal character to move to the next date part. The default value is True.

See Also




CaseSensitive Property True if string comparisons are case-sensitive; otherwise, False. Default: False.

Syntax

[VB]

Public Property CaseSensitive As Boolean

[C#]

public bool CaseSensitive {get; set;}

[Delphi]

property CaseSensitive: Boolean;

Remarks

The property value in a control is used as the default value in its sub-objects, for the following properties: ParseInfo.CaseSensitive, MaskInfo.CaseSensitive, PreValidation.CaseSensitive, PostValidation.CaseSensitive.

See Also





MaskInfo Class (page 224)

CausesValidation Property· 159

ParseInfo Class (page 209)


PreValidation Class (page 237)

CausesValidation Property Gets or sets a value indicating whether the control causes validation (i.e. calls Validated and Validating events).

Syntax

[VB]

Public Property CausesValidation As Boolean

[C#]

public bool CausesValidation {get; set;}

[Delphi]

property CausesValidation: Boolean;

Remarks

Default: True.

This property can be set to False only if TextDetached = True.

See Also



CopyWithLiterals Property (C1TextBox) Used with numeric input mode and edit mask. If True, text in the clipboard includes literals.

Syntax

[VB]

Public Property CopyWithLiterals As Boolean

[C#]

public bool CopyWithLiterals {get; set;}

[Delphi]

property CopyWithLiterals: Boolean;

Remarks

When control text is copied to the clipboard while the control is in NumericInput mode or its edit mask is active, setting CopyWithLiterals = False excludes literals from the clipboard text.

If CopyWithLiterals = True (default), the text is copied with literals included.

MaskInfo.CopyWithLiterals property uses the control's CopyWithLiterals property as its default value and can override it.


See Also




Culture Property Syntax

The culture ID.

[VB]

Public Property Culture As Integer

[C#]

public int Culture {get; set;}

[Delphi]

property Culture: Integer;

Remarks

Default: 0 (Current Culture).

See Also





CultureInfo Property The current CultureInfo object (available at runtime).

Syntax

[VB]

Public ReadOnly Property CultureInfo As CultureInfo

[C#]

public CultureInfo CultureInfo {get;}

[Delphi]

property CultureInfo: CultureInfo;

Remarks

Related Topic: Culture (Regional) Settings (page 26)

See Also


CultureName Property· 161




CultureName Property The name selected for the Culture property in the Properties grid.

Syntax

[VB]

Public ReadOnly Property CultureName As String

[C#]

public string CultureName {get;}

[Delphi]

property CultureName: string;

Remarks

The value of this property is “(Current Culture)”, “(Invariant Culture)” or one of CultureInfo.DisplayName values.


See Also





CurrentTimeZone Property If True, the control’s stored Value is in current time zone; otherwise, the Value is adjusted to the time zone defined by the GMTOffset property.

Syntax

[VB]

Public Property CurrentTimeZone As Boolean

[C#]

public bool CurrentTimeZone {get; set;}

[Delphi]

property CurrentTimeZone: Boolean;

Remarks

This property is True by default, which means that date-time values are invariant, not adjusted to time zones. If this property is set to False, the Text shown to the user and the underlying stored Value become different. The stored Value belongs to the time zone defined by the GMTOffset property specifying the offset in hours


and minutes of the base time zone from Greenwich Mean Time. The Text shown to the user belongs to the local time zone defined by the user computer settings. Displaying values and parsing values entered by the user, C1Input adjusts it to the time zone difference.

Related Topic: Editing Date and Time Values (page 30)

See Also





CustomFormat Property Custom format specifier used if FormatType = FormatTypeEnum.CustomFormat.

Syntax

[VB]

Public Property CustomFormat As String

[C#]

public string CustomFormat {get; set;}

[Delphi]

property CustomFormat: string;

Remarks

If FormatType = FormatTypeEnum.CustomFormat, this string is used according to the rules for .NET custom format specifiers. It is passes as an argument to the IFormattable.ToString() method for the appropriate data type.

See Custom format specifiers (page 19) for the description of supported custom format specifiers.

C1Input adds two special custom formats to the standard .NET custom format specifiers: True|False for boolean data type (see Numeric custom format specifiers (page 19)) and multiple date-time formats separated with section separator ‘|’, see Date-time custom format specifiers (page 21).

The property value in a control is used as the default value in its sub-objects, for the following properties: DisplayFormat.CustomFormat, EditFormat.CustomFormat, ParseInfo.CustomFormat. Default: empty string.

Related Topic: Formatting Data (page 16)

See Also





FormatInfo Class (page 204)

DataField Property· 163

DataField Property The field of the data source object to which the control is bound.

Syntax

[VB]

Public Property DataField As String

[C#]

public string DataField {get; set;}

[Delphi]

property DataField: string;

Remarks

This property, together with DataSource, is used for data binding. Do not use the (DataBindings) property inherited from Control to bind the Value or Text property to a data source, use DataSource/DataField instead.

Related Topic: Data Binding (page 15)

See Also






DataSource Property The data source object to which the control is bound.

Syntax

[VB]

Public Property DataSource As Object

[C#]

public object DataSource {get; set;}

[Delphi]

property DataSource: Object;

Remarks

This property, together with DataField, is used for data binding. Do not use the (DataBindings) property inherited from Control to bind the Value or Text property to a data source, use DataSource/DataField instead.

In C1DbNavigator, the DataSource property is used together with DataMember property that specifies a table in a multi-table data source. The DataField property is not used in C1DbNavigator.


Related Topic: Data Binding (page 15)

See Also







DataType Property Type of the Value property.

Syntax

[VB]

Public Property DataType As Type

[C#]

public Type DataType {get; set;}

[Delphi]

property DataType: Type;

Remarks

C1Input controls support the following built-in types: Boolean, Byte, Char, DateTime, Decimal, Double, Guid, Int16, Int32, Int64, Object, Single, String, TimeSpan, Uri. These types are available for selection at design time. Additional types (type names) can be typed manually in the DataType property at design time. These types are supported at run time if they support TypeConverter for string/value conversion.

C1NumericEdit control supports the following built-in types: Byte, Decimal, Double, Int16, Int32, Int64, Single.

In C1DateEdit control, the DataType property is always set to DateTime and cannot be changed.

When a control is bound to a data source, the DataType property is automatically set to the data type of the field to which the control is bound. However, it can be changed after binding the control, so the control’s Value and the field to which it is bound do not necessarily have the same type. If their types are different, the control and the data source will perform the necessary type conversion. In this case, it is the programmer’s responsibility to make sure this conversion is possible. For example, a control with DataType = Integer can be bound to a string DataField. In such case, an exception will be thrown if the field contains a string that cannot be converted to an integer.

See Also





DaylightTimeAdjustment Property· 165

DaylightTimeAdjustment Property The value specified in the GMTOffset property can be advanced or set back due to daylight-saving time changes. Default: NoAdjustments.

Syntax

[VB]

Public Property DaylightTimeAdjustment As DaylightTimeAdjustmentEnum

[C#]

public DaylightTimeAdjustmentEnum DaylightTimeAdjustment {get; set;}

[Delphi]

property DaylightTimeAdjustment: DaylightTimeAdjustmentEnum;

Remarks

This property is applicable only if CurrentTimeZone = False.

See Also





DisableOnNoData Property Gets or sets whether the text box should be disabled when it is bound to an empty data source, i.e. CurrencyManager.Count = 0.

Syntax

[VB]

Public Property DisableOnNoData As Boolean

[C#]

public bool DisableOnNoData { get; set; }

[Delphi]

property DisableOnNoData: Boolean;

Remarks

Default: True

See Also






DateTimeInput Property Whether or not a special edit mode is applied to DateTime values.

Syntax

[VB]

Public Property DateTimeInput As Boolean

[C#]

public bool DateTimeInput {get; set;}

[Delphi]

property DateTimeInput: Boolean;

Remarks

If True (default) and DataType = DateTime, values are edited using a special mode similar to the standard DateTimePicker control. Each date-time field, such as year, month, day, etc, is edited independently using numeric keys, up- and down-arrow keys and mouse wheel.


See Also




DisplayFormat Property Format used to display the value when the control is not in edit mode (does not have input focus or is read-only).

Syntax

[VB]

Public ReadOnly Property DisplayFormat As FormatInfo

[C#]

public FormatInfo DisplayFormat {get;}

[Delphi]

property DisplayFormat: FormatInfo;

Remarks


See Also




EditFormat Property· 167

EditFormat Property Format used to display the value when the control is in edit mode (has input focus and is not read-only).

Syntax

[VB]

Public ReadOnly Property EditFormat As FormatInfo

[C#]

public FormatInfo EditFormat {get;}

[Delphi]

property EditInfo: FormatInfo;

Remarks


See Also




EditMask Property The edit mask string restricting user input.

Syntax

[VB]

Public Property EditMask As String

[C#]

public string EditMask {get; set;}

[Delphi]

property EditMask: string;

Remarks

This value of this property in a control always has the same value as MaskInfo.EditMask.

See Edit Mask (page 27) for the description of edit mask special characters (placeholders).

See Also






EditMode Property Returns True, if the control has input focus and TextDetached = False.

Syntax

[VB]

Public ReadOnly Property EditMode As Boolean

[C#]

public bool EditMode {get;}

[Delphi]

property EditMode: Boolean;

See Also




EmptyAsNull Property If True, empty strings are interpreted as null values (DBNull).

Syntax

[VB]

Public Property EmptyAsNull As Boolean

[C#]

public bool EmptyAsNull {get; set;}

[Delphi]

property EmptyAsNull: Boolean;

Remarks

Default: False.

The property value in a control is used as the default value in its sub-objects, for the following properties: DisplayFormat.EmptyAsNull, EditFormat.EmptyAsNull, ParseInfo.EmptyAsNull, MaskInfo.EmptyAsNull.

Related Topic: Handling NULL and Empty Values (page 34)

See Also







ErrorInfo Property· 169

ErrorInfo Property Settings affecting error handling in the control.

Syntax

[VB]

Public ReadOnly Property ErrorInfo As ErrorInfo

[C#]

public ErrorInfo ErrorInfo {get;}

[Delphi]

property ErrorInfo: ErrorInfo;

Remarks

This property contains settings that are used as default values for error message, action on error and other information used in error handling. All these settings can be overridden in ValidationError event.

Related Topic: Error Handling (page 32)

See Also








FormatType Property Enumeration value determining the formatting method, including standard .NET format specifiers, custom and programmatic formatting.

Syntax

[VB]

Public Property FormatType As FormatTypeEnum

[C#]

public FormatTypeEnum FormatType {get; set;}

[Delphi]

property FormatType: FormatTypeEnum;

Remarks

See Format types (page 17) for the description of allowed format types.

Default: FormatTypeEnum.DefaultFormat


The property value in a control is used as the default value in its sub-objects, for the following properties: DisplayFormat.FormatType, EditFormat.FormatType, ParseInfo.FormatType.


See Also






GMTOffset Property The time zone of the Value property used if CurrentTimeZone = False.

Syntax

[VB]

Public Property GMTOffset As TimeSpan

[C#]

public TimeSpan GMTOffset {get; set;}

[Delphi]

property GMTOffset: TimeSpan;

Remarks

Related Topic: CurrentTimeZone and Editing Date and Time Values (page 30)

See Also





InitialSelection Property Determines the selection position when a control receives input focus. Default: InitialSelectionEnum.SelectAll.

Syntax

[VB]

Public Property InitialSelection As InitialSelectionEnum

[C#]

public InitialSelectionEnum InitialSelection {get; set;}

Label Property· 171

[Delphi]

property InitialSelection: InitialSelectionEnum;

See Also




Label Property Label control associated with this input field.

Syntax

[VB]

Public Property Label As System.Windows.Forms.Label

[C#]

public System.Windows.Forms.Label Label {get; set;}

[Delphi]

property Label: System.Windows.Forms.Label;

Remarks

When the user clicks the label, the input focus is moved to the corresponding C1TextBox or its descendant control. The user can activate the input field by pressing a mnemonic key specified in the associated label. The Enabled property of the label depends on the corresponding property of the input field.

See Also




Lines Property The lines of text in a multiline control.

Syntax

[VB]

Public Property Lines As String()

[C#]

public string[] Lines {get; set;}

property Lines: string;

Remarks

Setting Lines is an alternative way to set the Text property, so setting the Lines property has the same restrictions as described for the Text property.


See Also


Margins Property The spacing between the input control content and its edges, in pixels. Default: all margins are set to 0.

Syntax

[VB]

Public Property Margins As Margins

[C#]

public Margins Margins {get; set;}

[Delphi]

property Margins: Margins;

Remarks

C1.Win.C1Input.Margins class is similar to the standard class System.Drawing.Printing.Margins. For more information about this class see MSDN help.

See Also




MaskInfo Property Edit mask settings.

Syntax

[VB]

Public ReadOnly Property MaskInfo As MaskInfo

[C#]

public MaskInfo MaskInfo {get;}

[Delphi]

property MaskInfo: MaskInfo;

Remarks

Related Topic: Edit Mask (page 27)

See Also





MinShortYear Property· 173

MinShortYear Property The minimum year that can be entered without leading zeros.

Syntax

[VB]

Public Property MinShortYear As Integer

[C#]

public int MinShortYear {get; set;}

[Delphi]

property MinShortYear: Integer;

Remarks

The minimum year that can be entered without leading zeros (when DateTimeInput = True). For example, if MinShortYear = 300 (default), entering 200 is not allowed (will be ignored), whereas 400 is interpreted as 0400 A.D. Regardless of this property value, entering 0200 will be interpreted as year 0200 A.D.


See Also




Modified Property Gets or sets a value that indicates that the control has been modified by the user since the control received the input focus or its Value last set.

Syntax

[VB]

Public Property Modified As Boolean

[C#]

public bool Modified {get; set;}

[Delphi]

property Modified: Boolean;

See Also





NullText Property String representing a DBNull value.

Syntax

[VB]

Public Property NullText As String

[C#]

public string NullText {get; set;}

[Delphi]

property NullText: string;

Remarks

The property value in a control is used as the default value in its sub-objects, for the following properties: DisplayFormat.NullText, EditFormat.NullText, ParseInfo.NullText. Default: empty string

Related Topic: Handling NULL and Empty Values (page 34)

See Also







NumericInput Property Sets or gets a value indicating whether a special edit mode is used for numeric values.

Syntax

[VB]

Public Property NumericInput As Boolean

[C#]

public bool NumericInput {get; set;}

[Delphi]

property NumericInput: Boolean;

Remarks

When this property is set to True (default) and DataType is a numeric type, numeric value is edited in a special calculator-like mode. It accepts only digits, +/-, arrow keys, and, if data type and format allow, decimal point and exponent. Other characters, such as letters, are ignored.

NumericInputKeys Property· 175

See Also



NumericInputKeys Property Enables/disables the special keys used when NumericInput = True. Default: NumericInputKeyFlags.Standard.

Syntax

[VB]

Public Property NumericInputKeys As NumericInputKeyFlags

[C#]

public NumericInputKeyFlags NumericInputKeys {get; set;}

[Delphi]

property NumericInputKeys: NumericInputKeyFlags;

See Also



ParseInfo Property Settings affecting parsing, that is, converting the string entered by the user to the data type.

Syntax

[VB]

Public ReadOnly Property ParseInfo As ParseInfo

[C#]

public ParseInfo ParseInfo {get;}

[Delphi]

property ParseInfo: ParseInfo;

Remarks

Related Topic: Parsing (Updating) Data (page 26)

See Also





PostValidation Property Validation rules applied after parsing, that is, after converting the string entered by the user to the DataType (typed validation).

Syntax

[VB]

Public ReadOnly Property PostValidation As PostValidation

[C#]

public PostValidation PostValidation {get;}

[Delphi]

property PostValidation: PostValidation;

Remarks

Related Topic: Typed value validation (PostValidation) (page 29)

See Also




PreValidation Property Validation rules applied before parsing, that is, before converting the string entered by the user to the DataType (raw string validation).

Syntax

[VB]

Public ReadOnly Property PreValidation As PreValidation

[C#]

public PreValidation PreValidation {get;}

[Delphi]

property PreValidation: PreValidation;

Remarks

Related Topic: Input string validation (PreValidation) (page 29)

See Also




ShowContextMenu Property· 177

ShowContextMenu Property Specifies whether the context menu can be displayed for the control.

Syntax

[VB]

Public Property ShowContextMenu As Boolean

[C#]

public bool ShowContextMenu { get; set; }

[Delphi]

property ShowContextMenu: Boolean;

Remarks

Default: True

See Also





ShowFocusRectangle Property Specifies whether a focus rectangle should be displayed around the client area when the control has the input focus.

Syntax

[VB]

Public Property ShowFocusRectangle As Boolean

[C#]

public bool ShowFocusRectangle { get; set; }

[Delphi]

property ShowFocusRectangle: Boolean;

Remarks

Default: False

See Also






Text Property The current text in the control.

Syntax

[VB]

Public Property Text As String

[C#]

public string Text {get; set;}

[Delphi]

property Text: string;

Remarks

If TextDetached = False and the control is disabled, invisible or ReadOnly, this property cannot be set, it is read-only. Set the Value property instead, or set TextDetached = True if you need to set the Text property. Note: the C1Label control is always considered read-only.

See Also




TextDetached Property Specifies whether the Value and Text properties can be set independently.

Syntax

[VB]

Public Property TextDetached As Boolean

[C#]

public bool TextDetached {get; set;}

[Delphi]

property TextDetached: Boolean;

Remarks

This property is False by default, which means that setting Value automatically updates the control’s Text, and editing the control’s Text automatically updates Value when the user leaves the control, see Value and Text: Displaying, Validating and Updating Values (page 16).

If this property is set to True, setting Value does not change the control’s Text. The Text property can be set programmatically. The programmer can use DisplayFormat/EditFormat.Format, MaskInfo.GetDisplayText and other methods to format the text. The text can also be parsed programmatically using UpdateValueWithCurrentText, ParseContent, CheckValidationResult and other methods.

Related Topic: Value and Text: Displaying, Validating and Updating Values (page 16)

TrimEnd Property· 179

See Also




TrimEnd Property If True, trailing spaces are removed.

Syntax

[VB]

Public Property TrimEnd As Boolean

[C#]

public bool TrimEnd {get; set;}

[Delphi]

property TrimEnd: Boolean;

Remarks

Default: True.

The property value in a control is used as the default value in its sub-objects, for the following properties: DisplayFormat.TrimEnd, EditFormat.TrimEnd, PreValidation.TrimEnd, ParseInfo.TrimEnd.

See Also








TrimStart Property If True, leading spaces are removed.

Syntax

[VB]

Public Property TrimStart As Boolean

[C#]

public bool TrimStart {get; set;}

[Delphi]

property TrimStart: Boolean;


Remarks

Default: False.

The property value in a control is used as the default value in its sub-objects, for the following properties: DisplayFormat.TrimStart, EditFormat.TrimStart, PreValidation.TrimStart, ParseInfo.TrimStart.

See Also








UserCultureOverride Property If True, current user regional settings override the selected culture.

Syntax

[VB]

Public Property UserCultureOverride As Boolean

[C#]

public bool UserCultureOverride {get; set;}

[Delphi]

property UserCultureOverride: Boolean;

Remarks

Determines the CultureInfo.UseUserOverride value. If set to True, current user regional settings override the selected culture. Default: False.


See Also





Value Property· 181

Value Property The main bindable property of a C1Input control.

Syntax

[VB]

Public Property Value As Object

[C#]

public object Value {get; set;}

[Delphi]

property Value: Object;

Remarks

Related Topic: Data Binding (page 15) and Value and Text: Displaying, Validating and Updating Values

See Also





ValueIsDbNull Property Gets or sets a value indicating whether the Value is DBNull.

Syntax

[VB]

Public Property ValueIsDbNull As Boolean

[C#]

public bool ValueIsDbNull {get; set;}

[Delphi]

property ValueIsDbNull: Boolean;

Remarks

Setting this property to true sets the Value to DBNull. This property is needed for specifying null value at design time, and it can be used at run time as well. AllowDbNull is ignored when the value is set to DBNull programmatically, for example, via the ValueIsDbNull property.

See Also






VerticalAlign Property Vertical alignment of the contents in the control. Default: VerticalAlignEnum.Top.

Syntax

[VB]

Public Property VerticalAlign As VerticalAlignEnum

[C#]

public VerticalAlignEnum VerticalAlign {get; set;}

[Delphi]

property VerticalAlign: VerticalAlignEnum;

See Also




WrapDateTimeFields Property If this property is False the month will be automatically incremented when the user spins the date past the end of the month. The same about other parts of the date/time value.

Syntax

[VB]

Public Property WrapDateTimeFields As Boolean

[C#]

public bool WrapDateTimeFields { get; set; }

[Delphi]

property WrapDateTimeFields: Boolean;

Remarks

Default: True

See Also





CheckValidationResult Method· 183

C1TextBox Control Methods

CheckValidationResult Method Checks the result of the ParseContent method.

Syntax

[VB]

Public Function CheckValidationResult (reason As ErrorReasonEnum, ByRef parsedValue As Object, errorInfo As ErrorInfo) As Boolean

[C#]

public bool CheckValidationResult (ErrorReasonEnum reason, ref object parsedValue, ErrorInfo errorInfo)

[Delphi]

function CheckValidationResult (reason: ErrorReasonEnum; ByRef parsedValue: Object; errorInfo: ErrorInfo): Boolean;


ErrorReasonEnum reason

Value indicating the reason of validation failure.

object parsedValue Parsed value of type DataType that was undergoing validation.

ErrorInfo errorInfo Object detailing error information, if an error occurred.

Remarks

This method checks the result of the ParseContent method. If necessary, calls ValidationError event and then throws ValidationException if the event code so indicates.

Related Topic: Programmatic Formatting, Parsing and Validation (page 31)

See Also




DecDateTimeInput Method Decrements the currently selected field in DateTimeInput mode.

Syntax

[VB]

Public Sub DecDateTimeInput()

[C#]

public void DecDateTimeInput ()

[Delphi]

procedure DecDateTimeInput()


Remarks

If the control is in DateTimeInput mode, this method decrements the currently selected field (if any), or sets it to the last value when the first value is reached

See Also



IncDateTimeInput Method Increments the currently selected field in DateTimeInput mode.

Syntax

[VB]

Public Sub IncDateTimeInput()

[C#]

public void IncDateTimeInput ()

[Delphi]

property IncDateTimeInput()

Remarks

If the control is in DateTimeInput mode, this method increments the currently selected field (if any), or sets it to the first value when the last value is reached.


See Also



ParseContent Method Parses the Text string.

Syntax

[VB]

Public Function ParseContent(ByRef parsedValue As Object, ByRef errorInfo As ErrorInfo) As ErrorReasonEnum

[C#]

public ErrorReasonEnum ParseContent (out object parsedValue , out ErrorInfo errorInfo)

[Delphi]

function ParseContent (ByRef parsedValue: Object; ByRef errorInfo: ErrorInfo): ErrorReasonEnum;

ResetText Method· 185


object parsedValue Output parameter: Parsing result.

ErrorInfo errorInfo Output parameter: Object detailing error information, if an error occurred.

Remarks

This method tries to parse the contents of the Text property. If successful, it assigns the result to the parsedValue parameter and returns ErrorReasonEnum.NoErrors. If failed, it returns the error reason and assigns error description to the errorInfo parameter.


See Also




ResetText Method Updates the control's Text with the current Value.

Syntax

[VB]

Public Sub ResetText()

[C#]

public override void ResetText ()

[Delphi]

function ResetText()

Remarks

Unless TextDetached = True, this method updates the control's Text with the current Value. If TextDetached = True, it calls Control.ResetText.

See Also






SetProposedValue Method This method works exactly as setting the Value property, except that it does not change the internal variable storing the value before editing, so the user can press Esc and restore the previous value. This method works only in edit mode. If the control is not in edit mode, this methods does nothing.

Syntax

[VB]

Public Sub SetProposedValue (value As Object)

[C#]

public void SetProposedValue (object value)

[Delphi]

procedure SetPropsedValue (value: Object);

Remarks

This method is mainly used in a custom drop-down form, when your code changes the value of the control according to the selection or editing done by the end user in the dropdown form. You can set the Value property there, but that has a drawback that after Value is set the user cannot revert to the previous values pressing the Esc key. If you use the SetProposedValue instead, then the current value changes, but the previous values is not affected, so the user can still revert to the previous value with Esc key, as long as the control is still in edit mode.

See Also




SuspendNumericInput Method This method temporarily disables numeric input mode (see NumericInput property). It can be useful for custom dropdown forms used with C1DropDownContol. For example, you may need this method if you implement a custom dropdown calculator. The current value of a calculator does not necessarily conform to the format assigned to the control's FormatType/CustomFormat properties. While a calculator is open, the user expects to see the exact value produced by the calculator, not the formatted value, which can have less precision. To ensure this, you call SuspendNumericInput(true, true) when your calculator opens. The value will be parsed when the calculator is closed, at which point you call SuspendNumericInput(false, true).

Syntax

[VB]

Public Sub SuspendNumericInput(suspend As Boolean, updateValue As Boolean)

[C#]

public void SuspendNumericInput(bool suspend, bool updateValue)

[Delphi]

procedure SuspendNumericInput (suspend: Boolean; updateValue: Boolean);

UpdateValueWithCurrentText Method· 187


bool suspend True to suspend numeric input, False to resume it.

bool updateValue If True, control's Value is updated, obtained from the current control text. Both during numeric input and while it is suspended, control's Value does not reflect the current control text, Value gets updated only when the control loses focus. Therefore, when suspending numeric mode and resuming it, you usually need to update the Value property with the current control text, so it can be used by a dropdown (when suspending) and by the control in numeric input mode (when resuming). Passing False in this argument provides for ignoring the current control text and using the previous Value (ignoring changes made in numeric input mode when suspending; ignoring the changes made in dropdown when resuming).

See Also



UpdateValueWithCurrentText Method Triggers parsing of the Text property and updating the Value.

Syntax

[VB]

Public Function UpdateValueWithCurrentText() As Boolean

[C#]

public bool UpdateValueWithCurrentText ()

[Delphi]

function UpdateValueWithCurrentText (): Boolean;

Remarks

This method triggers parsing of the Text to the Value property. It can be used for immediate update of the Value regardless of the TextDetached setting. The method returns True if the Value property has been successfully updated.


See Also





C1TextBox Control Events

BindingFormatting Event Occurs when Value is retrieved from the data source.

Syntax

[VB]

Public Event BindingFormatting As ConvertEventHandler

[C#]

public event ConvertEventHandler BindingFormatting

[Delphi]

property BindingFormatting: ConvertEventHandler;

Remarks

This event can be used to change the type and value of the Value property when it is received from a data source field. For example, to bind a control to a data field whose type is different from the control's DataType, use this event (and BindingParsing, if the control is not read-only) to convert the type. You can also use this event to change the value before it is sent to the control.

To convert the value to a different type, or to change the value sent to the control, set the e.Value argument of the event.

Argument e.DesiredType is set to the value of the control's DataType property (for C1PictureBox, it is always System.Drawing.Image).

Related Topics: BindingParsing

See Also






BindingParsing Event Occurs when Value is stored in the data source.

Syntax

[VB]

Public Event BindingParsing As ConvertEventHandler

[C#]

public event ConvertEventHandler BindingParsing

[Delphi]

property BindingParsing: ConvertEventHandler;

CultureInfoSetup Event· 189

Remarks

This event can be used to change the type and value of the Value property when it is sent to the data source after being modified by the user. For example, to bind a control to a data field whose type is different from the control's DataType, use this event and BindingFormatting.

To convert the value to a different type, or to change the value sent to the data source, set the e.Value argument of the event.

Argument e.DesiredType is set to the type of the field the control is bound to. For an unbound control, it is set to Object.

Related Topics: BindingFormatting

See Also





CultureInfoSetup Event CultureInfo can be set up (on startup) or has been changed.

Syntax

[VB]

Public Event CultureInfoSetup As CultureInfoSetupEventHandler

[C#]

public event CultureInfoSetupEventHandler CultureInfoSetup

[Delphi]

property CultureInfoSetup: CultureInfoSetupEventHandler;

Remarks

This event occurs at startup and every time the Culture property is changed.

When the event is called, the CultureInfo argument of the event is set up according to the Culture setting. You can change the CultureInfo properties to adjust them to your application needs.


See Also






DataTypeChanged Event Occurs when the DataType property changes.

Syntax

[VB]

Public Event DataTypeChanged As EventHandler

[C#]

public event EventHandler DataTypeChanged

[Delphi]

property DataTypeChanged: EventHandler;

See Also




FormatError Event Occurs when the control receives data that cannot be formatted according to the current format and edit mask settings.

Syntax

[VB]

Public Event FormatError As FormatErrorEventHandler

[C#]

public event FormatErrorEventHandler FormatError

[Delphi]

property FormatError: FormatErrorEventHandler;

Remarks

Error occurs while formatting the stored value. For example, if CustomFormat contains two digits and the received Value is a three-digit number. FormatError is not called when the error is made by the end user typing in the control, in that case ValidationError is called. FormatError occurs when the control cannot format value for display.

If ErrorInfo.ErrorProvider:ErrorInfo property (or C1Label.ErrorProvider:C1Label in C1Label control) is set to an ErrorProvider component, C1Input uses that ErrorProvider component to signal errors after firing the FormatError event. The error description shown as ErrorProvider tooltip can be customized in FormatError code by setting the ErrorMessage event argument.


See Also




Formatted Event· 191

Formatted Event Occurs after the value has been formatted.

Syntax

[VB]

Public Event Formatted As FormatEventHandler

[C#]

public event FormatEventHandler Formatted

[Delphi]

property Formatted: FormatEventHandler;

Remarks


See Also





Formatting Event Formatting the value programmatically.

Syntax

[VB]

Public Event Formatting As FormatEventHandler

[C#]

public event FormatEventHandler Formatting

[Delphi]

property Formatting: FormatEventHandler;

Remarks

This event is fired if either DisplayFormat.FormatType or EditFormat.FormatType is equal to FormatTypeEnum.UseEvent. It is not called for null values, see Displaying NULL and empty values (page 34).


See Also






MarginsChanged Event Occurs when the Margins property or one of the margins has changed.

Syntax

[VB]

Public Event MarginsChanged As EventHandler

[C#]

public event EventHandler MarginsChanged

[Delphi]

property MarginsChanged: EventHandler;

See Also




Parsed Event Occurs after the input string value has been converted to the DataType.

Syntax

[VB]

Public Event Parsed As ParseEventHandler

[C#]

public event ParseEventHandler Parsed

[Delphi]

property Parsed: ParseEventHandler;

Remarks


See Also




Parsing Event· 193

Parsing Event Programmatic parsing of the input string.

Syntax

[VB]

Public Event Parsing As ParseEventHandler

[C#]

public event ParseEventHandler Parsing

[Delphi]

property Parsing: ParseEventHandler;

Remarks

Converting the string value entered by the user to the DataType when ParseInfo.FormatType = FormatTypeEnum.UseEvent.


See Also




PostValidated Event Occurs after the typed value has been validated.

Syntax

[VB]

Public Event PostValidated As PostValidationEventHandler

[C#]

public event PostValidationEventHandler PostValidated

[Delphi]

property PostValidated: PostValidationEventHandler;

Remarks


See Also





PostValidating Event Programmatic typed value validation.

Syntax

[VB]

Public Event PostValidating As PostValidationEventHandler

[C#]

public event PostValidationEventHandler PostValidating

[Delphi]

property PostValidating: PostValidationEventHandler;

Remarks

Use this event to validate typed value, after conversion from string, when PostValidation.Validation = PostValidationTypeEnum.PostValidationEvent.


See Also




PreValidated Event Occurs after the input string value has been validated.

Syntax

[VB]

Public Event PreValidated As PreValidationEventHandler

[C#]

public event PreValidationEventHandler PreValidated

[Delphi]

property PreValidated: PreValidationEventHandler;

Remarks


See Also




PreValidating Event· 195

PreValidating Event Programmatic input string validation.

Syntax

[VB]

Public Event PreValidating As PreValidationEventHandler

[C#]

public event PreValidationEventHandler PreValidating

[Delphi]

property PreValidating: PreValidationEventHandler;

Remarks

This event is fired to validate the input string value if PreValidation.Validation = PreValidationTypeEnum.PreValidatingEvent.


See Also




ValidationError Event Error occurred while parsing or validating the input string.

Syntax

[VB]

Public Event ValidationError As ValidationErrorEventHandler

[C#]

public event ValidationErrorEventHandler ValidationError

[Delphi]

property ValidationError: ValidationErrorEventHandler;

Remarks

Related Topic: Error handling (page 32)

See Also





ValueChanged Event Occurs when the Value changes.

Syntax

[VB]

Public Event ValueChanged As EventHandler

[C#]

public event EventHandler ValueChanged

[Delphi]

property ValueChanged: EventHandler;

See Also





VerticalAlignChanged Event Occurs when the value of the VerticalAlign property has changed.

Syntax

Public Event VerticalAlignChanged As EventHandler

[C#]

public event EventHandler VerticalAlignChanged

[Delphi]

property VerticalAlignChanged: EventHandler;

See Also




DateEditMonthCalendar Control· 197

DateEditMonthCalendar Control The calendar used as a dropdown in the C1DateEdit control.

System.Object System.MarshalByRefObject System.ComponentModel.Component System.Windows.Forms.Control System.Windows.Forms.MonthCalendar C1.Win.C1Input.DateEditMonthCalendar

DateEditMonthCalendar Members DateEditMonthCalendar Properties (properties inherited from MonthCalendar are not shown)

Date Currently selected date in the calendar.

DateIsNull Indicates if no date is currently selected.

ShowClearButton Determines if the Clear button of the dropdown calendar is visible.

ShowTodayButton Determines if the Today button of the dropdown calendar is visible.

UIStrings The string collection of user interface strings used in the calendar.

DateEditMonthCalendar Events (events inherited from MonthCalendar are not shown)

ClearButtonClick Occurs when the Clear button is clicked.

ClearButtonVisibilityChanged Occurs when Clear button visibility is changed.

DateChanged Occurs when the value of the Date property is changed.

DateSelected Occurs when the user selects a new value for the Date property.

TodayButtonClick Occurs when the Today button is clicked.

TodayButtonVisibilityChanged Occurs when Today button visibility is changed.


DateEditMonthCalendar Properties

Date Property Currently selected date in the calendar.

Syntax

[VB]

Public Property Date As DateTime

[C#]

public DateTime Date {get; set;}

[Delphi]

property Date: DateTime;

See Also

DateEditMonthCalendar Control (page 197)

DateIsNull Property Indicates if no date is currently selected.

Syntax

[VB]

Public Property DateIsNull As Boolean

[C#]

public bool DateIsNull {get; set;}

[Delphi]

property DateIsNull: Boolean;

See Also


ShowTodayButton Property Determines if the Today button of the dropdown calendar is visible.

Syntax

[VB]

Public Property ShowTodayButton As Boolean

[C#]

public bool ShowTodayButton {get; set;}

[Delphi]

property ShowTodayButton: Boolean;

ShowClearButton Property· 199

See Also


ShowClearButton Property Determines if the Clear button of the dropdown calendar is visible.

Syntax

[VB]

Public Property ShowClearButton As Boolean

[C#]

public bool ShowClearButton {get; set;}

[Delphi]

property ShowClearButton: Boolean;

See Also


UIStrings Property (DateEditMonthCalendar) The string collection of user interface strings used in the calendar.

Syntax

[VB]


[C#]


[Delphi]


Remarks

Use this property to customize or localize the strings shown to the end user. It contains button caption strings: "Today" and "Clear".

See Also


DateEditMonthCalendar Events

ClearButtonClick Event Occurs when the Clear button is clicked.

Syntax

[VB]

Public Event ClearButtonClick(sender As Object, e As EventArgs) As EventHandler


[C#]

public event EventHandler ClearButtonClick

[Delphi]

property ClearButtonClick: EventHandler;

Remarks

This event applies to the Calendar Property in the C1DateEdit Control.

See Also


ClearButtonVisibilityChanged Event Occurs when Clear button visibility is changed.

Syntax

[VB]

Public Event ClearButtonVisibilityChanged As EventHandler

[C#]

public event EventHandler ClearButtonVisibilityChanged

[Delphi]

property ClearButtonVisibilityChanged: EventHandler;

See Also


DateChanged Event Occurs when the value of the Date property is changed.

Syntax

[VB]

Public Event DateChanged As NullableDateTimeEventHandler

[C#]

public event NullableDateTimeEventHandler DateChanged

[Delphi]

property DateChanged: NullableDateTimeEventHandler;

See Also


DateSelected Event· 201

DateSelected Event Occurs when the user selects a new value for the Date property.

Syntax

[VB]

Public Event DateSelected As NullableDateTimeEventHandler

[C#]

public event NullableDateTimeEventHandler DateSelected

[Delphi]

property DateSelected: NullableDateTimeEventHandler;

See Also


TodayButtonClick Event Occurs when the Today button is clicked.

Syntax

[VB]

Public Event TodayButtonClick(sender As Object, e As EventArgs) As EventHandler

[C#]

public event EventHandler TodayButtonClick

[Delphi]

property TodayButtonClick: EventHandler;

Remarks

This event applies to the Calendar Property in the C1DateEdit Control.

See Also


TodayButtonVisibilityChanged Event Occurs when Today button visibility is changed.

Syntax

[VB]

Public Event TodayButtonVisibilityChanged As EventHandler

[C#]

public event EventHandler TodayButtonVisibilityChanged

[Delphi]

property TodayButtonVisibilityChanged: EventHandler;


See Also


NumericEditCalculator Control The calculator used as a dropdown in the C1NumericEdit control.

System.Object System.MarshalByRefObject System.ComponentModel.Component System.Windows.Forms.Control C1.Win.C1Input.NumericEditCalculator

NumericEditCalculator Members NumericEditCalulator Properties (properties inherited from Control are not shown)

ButtonFlatStyle Determines the style of the dropdown calculator buttons.

DisplayFormat Custom format specifier used to format the value displayed in the dropdown calculator.

FormatOnClose Gets or sets whether StoredFormat should be applied to the value entered in the dropdown calculator.

StoredFormat Custom format specifier used to format the stored value of the dropdown calculator.

UIStrings The collection of user interface strings -context menu items.

UseStaticMemory Gets or sets whether Static Memory context menu should appear for the dropdown calculator.

NumericEditCalculator Properties

ButtonFlatStyle Property Determines the style of the dropdown calculator buttons. Default: FlatStyle.Standard.

Syntax

[VB]

Public Property ButtonFlatStyle As FlatStyle

[C#]

public FlatStyle ButtonFlatStyle {get; set;}

[Delphi]

property ButtonFlatStyle: FlatStyle;

DisplayFormat Property· 203

Remarks

To enable XP styles for the dropdown calculator set this property to FlatStyle.System.

See Also

NumericEditCalculator Control (page 202)

DisplayFormat Property Custom format specifier used to format the value displayed in the dropdown calculator. Default: an empty string.

Syntax

[VB]

Public Property DisplayFormat As String

[C#]

public string DisplayFormat {get; set;}

[Delphi]

property DisplayFormat: string;

See Also


FormatOnClose Property Gets or sets whether StoredFormat should be applied to the value entered in the dropdown calculator.

Syntax

[VB]

Public Property FormatOnClose As Boolean

[C#]

public bool FormatOnClose {get; set;}

[Delphi]

property FormatOnClose: Boolean;

See Also


StoredFormat Property Custom format specifier used to format the stored value of the dropdown calculator. Default: 'F'.

Syntax

[VB]

Public Property StoredFormat As String


[C#]

public string StoredFormat {get; set;}

[Delphi]

property StoredFormat: string;

See Also


UIStrings Property (NumericEditCalculator) The collection of user interface strings - context menu items.

Syntax

[VB]


[C#]


[Delphi]


Remarks

Gets or sets whether Static Memory context menu should appear for the dropdown calculator.

See Also


UseStaticMemory Property Gets or sets whether Static Memory context menu should appear for the dropdown calculator. Default: True.

Syntax

[VB]

Public Property UseStaticMemory As Boolean

[C#]

public bool UseStaticMemory {get; set;}

[Delphi]

property UseStaticMemory: Boolean;

Remarks

The static memory is eight memory cells of type Decimal, which are shared by all instances of C1NumericEdit controls within the same application. The special context menu appears only if the ContextMenu property is not assigned by the user to some custom menu.

See Also


CustomFormat Property (FormatInfo)· 205

FormatInfo Class Settings for data formatting, converting data to string.

System.Object System.MarshalByRefObject C1.Win.C1Input.FormatInfo

Remarks


FormatInfo Members FormatInfo Properties




Inherit Manages inheritance of the FormatInfo properties from the host control properties.




FormatInfo Methods

Format Formats a value, converts it to a string.

FormatInfo Class Properties

CustomFormat Property (FormatInfo) Custom format specifier used if FormatType = FormatTypeEnum.CustomFormat.

Syntax

[VB]


[C#]



[Delphi]


Remarks

If FormatType = FormatTypeEnum.CustomFormat, this string is passed as an argument to IFormattable.ToString()

Related Topic: CustomFormat and Formatting Data (page 16)

See Also


EmptyAsNull Property (FormatInfo) If True, empty strings are interpreted as null values (DBNull).

Syntax

[VB]


[C#]


[Delphi]


Remarks

Default: False.

Related Topic: EmptyAsNull

See Also


FormatType Property (FormatInfo) Enumeration value determining the formatting method, including standard .NET format specifiers, custom and programmatic formatting.

Syntax

[VB]


[C#]


[Delphi]


Remarks

Related Topic: FormatType and Formatting Data (page 16)

Inherit Property (FormatInfo)· 207

See Also


Inherit Property (FormatInfo) Manages inheritance of the FormatInfo properties from the host control properties.

Syntax

[VB]

Public Property Inherit As FormatInfoInheritFlags

[C#]

public FormatInfoInheritFlags Inherit {get; set;}

[Delphi]

property Inherit: FormatInfoInheritFlags;

Remarks

This property manages inheritance of FormatType, CustomFormat, NullText, EmptyAsNull, TrimStart, TrimEnd properties from the corresponding properties of the control. Default: all properties are inherited.

See Also


NullText Property (FormatInfo) String representing a DBNull value.

Syntax

[VB]


[C#]


[Delphi]


Remarks

Related Topic: NullText

See Also



TrimEnd Property (FormatInfo) If True, trailing spaces are removed.

Syntax

[VB]


[C#]


[Delphi]


Remarks

Default: True.

Related Topic: TrimStart

See Also


TrimStart Property (FormatInfo) If True, leading spaces are removed.

Syntax

[VB]


[C#]


[Delphi]


Remarks

Default: False.


See Also


Format Method· 209

FormatInfo Class Methods

Format Method Formats a value, converts it to a string.

Syntax

[VB]

Public Function Format(value As Object) As String

[C#]

public string Format (object value)

[Delphi]

function Format(value: Object): string;


object value Typed value to convert to a string.

[VB]

Public Function Format(value As Object, formatType As FormatTypeEnum, CultureInfo Culture) As String

[C#]

public string Format (object value, FormatTypeEnum formatType, CultureInfo Culture)

[Delphi]

function Format(value: Object; formatType: FormatTypeEnum; CultureInfo: Culture): string;


object value Typed value to convert to a string.

FormatTypeEnum formatType

Format method or specifier used for conversion.

CultureInfo Culture Culture used for conversion.

Remarks

This method formats the value returning the resulting formatted string. It uses the current settings of the FormatInfo object. The second override uses specified formatType argument instead of FormatType and also uses specified culture.

See Also



ParseInfo Class Contains settings affecting parsing, that is, converting a string to the required data type.

System.Object System.MarshalByRefObject C1.Win.C1Input.ParseInfo

Remarks


ParseInfo Members ParseInfo Properties


CustomFormat String containing allowed date/time formats separated with '|' or a boolean pair "TrueValue|FalseValue".

DateTimeStyle Determines the styles (flags) permitted in input strings representing date/time.



FormatType The format used for parsing.

Inherit Manages inheritance of the ParseInfo properties from the host control properties.

NullText The string representing DBNull value.

NumberStyle Determines the styles (flags) permitted in input strings representing numbers.

TrimEnd If True, trailing spaces are removed before parsing.

TrimStart If True, leading spaces are removed before parsing.

ParseInfo Methods

IsTextDbNull Returns True if the argument represents a null value (DBNull).

Parse Converts text to the specified data type.

ParseBoolean Converts the text to a Boolean value.

ParseDateTime Converts text to a value using one of DateTime formats.

CaseSensitive Property (ParseInfo)· 211

ParseFixed Converts the text to a Decimal value using a fixed numeric format.

ParseFloat Converts the text to a Double value using a float numeric format.

ParseInteger Converts the text to Int64 value using an integer numeric format.

ParseInfo Class Properties

CaseSensitive Property (ParseInfo) True if string comparisons are case-sensitive; otherwise, False.

Syntax

[VB]


[C#]


[Delphi]


Remarks

This property defines whether comparison with NullText:ParseInfo and parsing of enum values, such as Yes/No, True/False, is case-sensitive. Default: False.

Related Topic: CaseSensitive

See Also


CustomFormat Property (ParseInfo) Custom format specifier used if FormatType = FormatTypeEnum.CustomFormat.

Syntax

[VB]


[C#]


[Delphi]



Remarks

This property inherits from and can override the control property CustomFormat.

In ParseInfo, this property is used only for DateTime and boolean values (other types can be parsed without custom format specifiers). In both cases it can contain multiple strings separated with ‘|’, see CustomFormat.

Related Topic: CustomFormat

See Also


DateTimeStyle Property Determines the styles (flags) permitted in input strings representing date/time.

Syntax

[VB]

Public Property DateTimeStyle As DateTimeStyleFlags

[C#]

public DateTimeStyleFlags DateTimeStyle {get; set;}

[Delphi]

property DateTimeStyle: DateTimeStyleflags;

Remarks

Fine-tuning settings for date/time parsing. Unlike NumberStyle, this property is applied parsing any date/time format, not just for custom date/time formats. Default: DateTimeStyleFlags.AllowWhiteSpaces. This value corresponds to calling the DateTime.Parse() method without the styles argument.

See Also


EmptyAsNull Property (ParseInfo) If True, empty strings are interpreted as null values (DBNull).

Syntax

[VB]


[C#]


[Delphi]


Remarks

Related Topic: EmptyAsNull

ErrorMessage Property (ParseInfo)· 213

See Also


ErrorMessage Property (ParseInfo) Error message shown in the standard message box and/or in the exception.

Syntax

[VB]

Public Property ErrorMessage As String

[C#]

public string ErrorMessage {get; set;}

[Delphi]

property ErrorMessage: string;

Remarks

This string is used as the error description if an error occurs while parsing an input string.


See Also


FormatType Property (ParseInfo) The format used for parsing.

Syntax

[VB]


[C#]


[Delphi]


Remarks

If not overridden, this property is inherited from EditFormat.FormatType.

Related Topic: FormatType

See Also



Inherit Property (ParseInfo) Syntax

[VB]

Public Property Inherit As ParseInfoInheritFlags

[C#]

public ParseInfoInheritFlags Inherit {get; set;}

[Delphi]

property Inherit: ParseInfoInheritFlags;

Remarks

This property manages inheritance of CaseSensitive, FormatType, DateTimeFormats, NullText, EmptyAsNull, TrimStart, TrimEnd properties from the corresponding properties of the control (DateTimeFormats inherits from CustomFormat). Default: all properties are inherited.

See Also


NullText Property (ParseInfo) The string representing DBNull value.

Syntax

[VB]


[C#]


[Delphi]


Remarks

Related Topic: NullText

See Also


NumberStyle Property Determines the styles (flags) permitted in input strings representing numbers.

Syntax

[VB]

Public Property NumberStyle As NumberStyleFlags

TrimEnd Property (ParseInfo)· 215

[C#]

public NumberStyleFlags NumberStyle {get; set;}

[Delphi]

property NumberStyle: NumberStyleFlags;

Remarks

Fine-tuning settings for numeric parsing. This property is used only if FormatType:ParseInfo = FormatTypeEnum.CustomFormat. Default: NumberStyleFlags.Any.

See Also


TrimEnd Property (ParseInfo) If True, trailing spaces are removed before parsing.

Syntax

[VB]


[C#]


[Delphi]


Remarks

Default: True.

Related Topic: TrimEnd

See Also


TrimStart Property (ParseInfo) If True, leading spaces are removed before parsing.

Syntax

[VB]


[C#]


[Delphi]



Remarks

Default: False.


See Also


ParseInfo Class Methods

IsTextDbNull Method Returns True if the argument represents a null value (DBNull).

Syntax

[VB]

Public Function IsTextDbNull (text As String, culture As CultureInfo) As Boolean

[C#]

public bool IsTextDbNull (string text, CultureInfo culture)

[Delphi]

function IsTextDbNull (text: String; culture: CultureInfo): Boolean;


string text The string to parse.

CultureInfo culture Culture used in parsing.

Remarks

Returns True if the text is equal to NullText:ParseInfo (or the text is empty and EmptyAsNull:ParseInfo = True), which means the value is DBNull.

See Also


Parse Method Converts text to the specified data type.

Syntax

[VB]

Public Function Parse(text As String, destinationType As Type, ByRef result As Object, errorInfo As ErrorInfo) As Boolean

[C#]

public bool Parse (string text, Type destinationType, out object result, ErrorInfo errorInfo)

[Delphi]

function Parse (text: String; destinationType: Type; ByRef result: Object; errorInfo: ErrorInfo): Boolean;

ParseBoolean Method· 217



Type destinationType Type to which the string is converted.

object result Conversion result.

ErrorInfo errorInfo Object detailing error information, if an error occurred.

Remarks

Returns True if parsing was successful, False otherwise.

See Also


ParseBoolean Method Converts the text to a Boolean value.

Syntax

[VB]

Public Function ParseBoolean(text As String, formatType As FormatTypeEnum, culture As CultureInfo) As Boolean

[C#]

public bool ParseBoolean (string text, FormatTypeEnum formatType, CultureInfo culture)

[Delphi]

function ParseBoolean (text: String; formatType: FormatTypeEnum; culture: CultureInfo): Boolean;




Format type used in parsing.


Remarks

The formatType parameter can have one of the following values: YesNo, TrueFalse, OnOff. The text does not have to contain all letters of the value string representation, the boolean value is detected by first letters, for example, "Y" instead of "Yes", "N" instead of "No".

See Also



ParseDateTime Method Converts text to a value using one of DateTime formats.

Syntax

[VB]

Public Function ParseDateTime(text As String, formatType As FormatTypeEnum, culture As CultureInfo) As DateTime

[C#]

public DateTime ParseDateTime (string text, FormatTypeEnum formatType, CultureInfo culture)

[Delphi]

function ParseDateTime (text: String; formatType: FormatTypeEnum; culture: CultureInfo): DateTime;






Remarks

The formatType parameter can be one of the following: GeneralDate, LongDate, MediumDate, ShortDate, LongTime, MediumTime, ShortTime, LongDateShortTime, LongDateLongTime, ShortDateShortTime, ShortDateLongTime, MonthAndDay, DateAndTimeGMT, DateTimeSortable, GMTSortable, LongDateTimeGMT,YearAndMonth.

See Also


ParseFixed Method Converts the text to a Decimal value using a fixed numeric format.

Syntax

[VB]

Public Function ParseFixed(text As String, formatType As FormatTypeEnum, culture As CultureInfo) As Decimal

[C#]

public Decimal ParseFixed (string text, FormatTypeEnum formatType, CultureInfo culture)

[Delphi]

function ParseFixed (text: String; formatType: FormatTypeEnum;, culture: CultureInfo): Decimal;

ParseFloat Method· 219






Remarks

The formatType parameter can have one of the following values: GeneralNumber, Currency, FixedPoint, StandardNumber, Percent.

See Also


ParseFloat Method Converts the text to a Double value using a float numeric format.

Syntax

[VB]

Public Function ParseFloat(text As String, formatType As FormatTypeEnum, culture As CultureInfo) As Double

[C#]

public Double ParseFloat (string text, FormatTypeEnum formatType, CultureInfo culture)

[Delphi]

function ParseFloat (text: String; formatType: FormatTypeEnum; culture: CultureInfo): Double;






Remarks

The formatType parameter can have one of the following values: GeneralNumber, Scientific, RoundTrip.

See Also



ParseInteger Method Converts the text to Int64 value using an integer numeric format.

Syntax

[VB]

Public Function ParseInteger(text As String, formatType As FormatTypeEnum, culture As CultureInfo) As Int64

[C#]

public Int64 ParseInteger (string text, FormatTypeEnum formatType, CultureInfo culture)

[Delphi]

function ParseInteger (text: string; formatType: FormatTypeEnum; culture: CultureInfo): Int64;






Remarks

The formatType parameter can have one of the following values: GeneralNumber, Integer, Hexadecimal.

See Also


Margins Class Represents the four margins around a control’s content.

System.Object C1.Win.C1Input.Margins

Margins Members Margins Properties

Bottom Gets or sets the bottom margin, in pixels.

Left Gets or sets the left margin, in pixels.

Right Gets or sets the right margin, in pixels.

Top Gets or sets the top margin, in pixels.

Margins Methods

Reset Sets all margins to zero.

Margins Constructor· 221

Set (overloaded) Sets the margin values.

ShouldSerialize Returns true if at least one margin differs from the default zero value. Otherwise, returns false.

Margins Events

Changed Occurs when at least one of the four margins changes.

Public Constructors

Margins Constructor Syntax

[VB]

Public Sub New()

Public Sub New(Integer, Integer, Integer, Integer)

[C#]

public void Margins();

public void Margins(int left, int right, int top, int bottom);

[Delphi]

constructor Create();

constructor Create(left: Integer; right: Integer; top: Integer; bottom: Integer);

Remarks

The first overload creates an instance of the class with all margins set to zero.

The second overload creates an instance of the class with the specified values for individual margins.

See Also

Margins Class (page 220)

Margins Properties

Bottom Property Gets or sets the bottom margin, in pixels.

Syntax

[VB]

Public Property Bottom() As Integer

[C#]

public int Bottom {get; set;}


[Delphi]

public Bottom: Integer;

See Also


Left Property Gets or sets the left margin, in pixels.

Syntax

[VB]

Public Property Left() As Integer

[C#]

public int Left {get; set;}

[Delphi]

public Left: Integer;

See Also


Right Property Gets or sets the right margin, in pixels.

Syntax

[VB]

Public Property Right() As Integer

[C#]

public int Right {get; set;}

[Delphi]

public Right: Integer;

See Also


Top Property Gets or sets the top margin, in pixels.

Syntax

[VB]

Public Property Top() As Integer

[C#]

public int Top {get; set;}

Reset Method· 223

[Delphi]

public Top: Integer;

See Also


Margins Methods

Reset Method Sets all margins to zero.

Syntax

[VB]

Public Sub Reset()

[C#]

public void Reset()

[Delphi]

procedure Reset();

See Also


Set Method Overloaded. Sets the margin values.

Syntax

[VB]

Public Sub Set(ByVal left As Integer, ByVal right As Integer, ByVal top As Integer, ByVal bottom As Integer)

Public Sub Set(ByVal printMargins As System.Drawing.Printing.Margins)

[C#]

public void Set ( System.Int32 left , System.Int32 right , System.Int32 top , System.Int32 bottom )

public void Set ( System.Drawing.Printing.Margins printMargins )

[Delphi]

procedure Set (left: Integer; right: Integer; top: Integer; bottom: Integer);

procedure Set (printMargins: System.Drawing.Printing.Margins)

Remarks

The first overload sets the four margins from the four passed values.

The second overload sets the four margins from the corresponding values of the System.Drawing.Printing.Margins class. No conversion is done on the values, they are treated as pixels.

See Also



ShouldSerialize Method Returns true if at least one margin differs from the default zero value. Otherwise, returns false.

Syntax

[VB]

Public Function ShouldSerialize() As Boolean

[C#]

public bool ShouldSerialize();

[Delphi]

function ShouldSerialize(): Boolean;

Remarks

The first overload sets the four margins from the four passed values.

The second overload sets the four margins from the corresponding values of the System.Drawing.Printing.Margins class. No conversion is done on the values, they are treated as pixels.

See Also


Margins Events

Changed Event Occurs when at least one of the four margins changes.

Syntax

[VB]

Public Event Changed As EventHandler

[C#]

public event EventHandler Changed;

[Delphi]

property Changed: EventHandler;

See Also


MaskInfo Class Contains edit mask settings.

System.Object System.MarshalByRefObject C1.Win.C1Input.MaskInfo

Remarks


MaskInfo Class· 225

MaskInfo Members MaskInfo Properties

AutoTabWhenFilled If True, focus automatically moves to the next control when the mask is filled.


Content Text entered by the user without literals (mask literals stripped).

CopywithLiterals If True, text in the clipboard includes literals.

CustomPlaceholders The collection of user-defined mask characters.

EditablePositionCount Returns the number of editable positions in the edit mask.

EditMask The edit mask string restricting user input.

EffectiveText Text in a readable format, with literals and without blanks.



Inherit Manages inheritance of the MaskInfo properties from the host control properties.

PromptChar Character displayed on empty mask positions.

SaveBlanks If True, the stored text includes blank positions as StoredEmptyChar.

SaveLiterals If True (default), the stored text (StoredContent) includes literals.

ShowLiterals Literal display mode.

SkipOptional If True (default), optional mask positions are automatically skipped until the first position allowing the typed character.

StoredContent The stored string obtained from the user input string.

StoredEmptyChar Character stored in empty mask positions.


MaskInfo Methods

GetContent Returns the string containing characters entered by the user, including those on optional positions that were left blank (skipped).

GetDisplayText Returns a string formatted for display using edit mask.

GetStoredText Returns the string that will be stored in the database, in accordance with current values of SaveLiterals, SaveBlanks and StoredEmptyChar properties.

IsMaskedMode Returns True if EditMask is non-empty and the control is in edit mode.

IsValid Returns True if the input string is valid with respect to the edit mask.

ResetContent Resets the text to the string representing a DBNull value.

MaskInfo Class Properties

AutoTabWhenFilled Property If True, focus automatically moves to the next control when the mask is filled.

Syntax

[VB]

Public Property AutoTabWhenFilled As Boolean

[C#]

public bool AutoTabWhenFilled {get; set;}

[Delphi]

property AutoTabWhenFilled: Boolean;

Remarks

Default: False.


See Also


CaseSensitive Property (MaskInfo) True if string comparisons are case-sensitive; otherwise, False.

Syntax

[VB]


Content Property· 227

[C#]


[Delphi]


Remarks

Affects matching literal characters. Determines whether matching input characters with mask literals is case-sensitive

Related Topic: CaseSensitive

See Also


Content Property Text entered by the user without literals (mask literals stripped).

Syntax

[VB]

Public Property Content As String

[C#]

public string Content {get; set;}

[Delphi]

property Content: string;

Remarks


See Also


CopyWithLiterals Property (MaskInfo) If True, text in the clipboard includes literals.

Syntax

[VB]

Public Property CopyWithLiterals As Boolean

[C#]

public bool CopyWithLiterals {get; set;}

[Delphi]

property CopyWithLiterals: Boolean;


Remarks When control text is copied to the clipboard while its edit mask is active, setting CopyWithLiterals = False excludes literals from the clipboard text. If CopyWithLiterals = True (default), the text is copied with literals included.

See Also MaskInfo Class (page 224)

CustomPlaceholders Property (MaskInfo) The collection of user-defined mask characters.

Syntax

[VB]

Public ReadOnly Property CustomPlaceholders As PlaceholderCollection

[C#]

public PlaceholderCollection CustomPlaceholders {get;}

[Delphi]

property CustomPlaceHolders: PlaceholderCollection;

Remarks

See CustomPlaceholder class for the description of a user-defined mask character.


See Also


EditablePositionCount Property Returns the number of editable positions in the edit mask.

Syntax

[VB]

Public ReadOnly Property EditablePositionCount As Integer

[C#]

public int EditablePositionCount {get;}

[Delphi]

property EditablePositionCount: Integer;

Remarks


See Also


EditMask Property (MaskInfo)· 229

EditMask Property (MaskInfo) The edit mask string restricting user input.

Syntax

[VB]

Public Property EditMask As String

[C#]

public string EditMask {get; set;}

[Delphi]

property EditMask: string;

Remarks

See Edit Mask (page 27) for the description of edit mask special characters (placeholders).

Related Topic: EditMask

See Also


EffectiveText Property Text in a readable format, with literals and without blanks.

Syntax

[VB]

Public Property EffectiveText As String

[C#]

public string EffectiveText {get; set;}

[Delphi]

property EffectiveText: string;

Remarks

This run-time only property allows the programmer to get or set the text in a control with edit mask in readable format, with literals and without blanks. This is the text as it will appear when the control will lose input focus.

See Also


EmptyAsNull Property (MaskInfo) If True, empty strings are interpreted as null values (DBNull).

Syntax

[VB]



[C#]


[Delphi]


Remarks

If this property is True and the user clears the contents of the masked control, the control’s Value is set to DBNull. If EmptyAsNull = False, empty text is interpreted as unchanged Value. Default: false.

Related Topic: Handling NULL and Empty Values (page 34) and EmptyAsNull

See Also


ErrorMessage Property (MaskInfo) Error message shown in the standard message box and/or in the exception.

Syntax

[VB]


[C#]


[Delphi]


Remarks

This string is used as the error description if an error occurs while parsing an input string with Edit mask, the input string does not match the edit mask.


See Also


Inherit Property (MaskInfo) Manages inheritance of the MaskInfo properties from the host control properties.

Syntax

[VB]

Public Property Inherit As MaskInfoInheritFlags

[C#]

public MaskInfoInheritFlags Inherit {get; set;}

PromptChar Property· 231

[Delphi]

property Inherit: MaskInfoInheritFlags;

Remarks

Manages inheritance of CaseSensitive, EmptyAsNull and TrimEnd properties from the control. Default: all properties are inherited

See Also


PromptChar Property Character displayed on empty mask positions.

Syntax

[VB]

Public Property PromptChar As char

[C#]

public char PromptChar {get; set;}

[Delphi]

property PromptChar: char;

Remarks

Default: '_'.


See Also


SaveBlanks Property If True, the stored text includes blank positions as StoredEmptyChar.

Syntax

[VB]

Public Property SaveBlanks As Boolean

[C#]

public bool SaveBlanks {get; set;}

[Delphi]

property SaveBlanks: Boolean;

Remarks

This property, together with SaveLiterals and StoredEmptyChar, determines how the text entered by the used is saved in the database. For example, consider input string "2__.15_e+6__" where '.' and 'e' are mask literals and '_' indicates a blank position (left empty by the user):


SaveLiterals = True, SaveBlanks = False (default)

Input string is saved with literals but omitting the blanks: "2.15e+6". Caution: literals following the last entered position are not stored with this option. For example, input string "2__.15_e____" will be stored as "2.15".

SaveLiterals = False, SaveBlanks = True

Literals are excluded while the blank positions are present. Each position containing PromptChar (those positions are considered blank) is replaced with StoredEmptyChar. For example, if PromptChar = '_', StoredEmptyChar = '*', the following string is stored: "2**15*+6**".

SaveLiterals = True, SaveBlanks = True

Both literals and blanks are stored. Each position containing PromptChar (those positions are considered blank) is replaced with StoredEmptyChar. For example, if PromptChar = '_', StoredEmptyChar = '*', the following string is stored: "2**.15*e+6**".

SaveLiterals = False, SaveBlanks = False

Both literals and blanks are omitted: "215+6". Caution: using this option can cause losing information, so showing the stored string in the control again can sometimes produce unexpected results.

See Also


SaveLiterals Property If True (default), the stored text (StoredContent) includes literals.

Syntax

[VB]

Public Property SaveLiterals As Boolean

[C#]

public bool SaveLiterals {get; set;}

[Delphi]

property SaveLiterals: Boolean;

Remarks


See Also


ShowLiterals Property Literal display mode.

Syntax

[VB]

Public Property ShowLiterals As ShowLiteralsEnum

[C#]

public ShowLiteralsEnum ShowLiterals {get; set;}

SkipOptional Property· 233

[Delphi]

property ShowLiterals: ShowLiteralsEnum;

Remarks

See ShowLiteralsEnum for the description of supported modes.


See Also


SkipOptional Property If True (default), optional mask positions are automatically skipped until the first position allowing the typed character.

Syntax

[VB]

Public Property SkipOptional As Boolean

[C#]

public bool SkipOptional {get; set;}

[Delphi]

property SkipOptional: Boolean;

Remarks

This property, True by default, enables the following edit mask functionality. If the caret is positioned on an optional character, and the user types a character that is not allowed on this position, then C1Input looks ahead for the first position allowing this character. If such position is found and there are only optional positions between it and the current position, then the caret skips the optional positions, leaves them blank, and the typed character appears on the found position.

With numbers, SkipOptional is usually applied in conjunction with '!' and '^' mask characters controlling the alignment of blanks to the right or left. Blanks before decimal point are usually aligned to the left, and blanks after decimal point - to the right. However, using special characters '!' and '^' is not mandatory, parsing of the input text will work correctly regardless of the blank alignment.

For example, consider an edit mask !990.^9999?#9. Suppose the user wants types 1.23e-4. If SkipOptional = True, the user can simply type these characters without using arrow keys to move the caret. Here is how the input looks, step by step:

enter control ¦__._______

press '1' 1¦_._______

press '.' __1.¦______

press '2' __1.2¦_____

press '3' __1.23¦____

press 'e' __1.23__e¦_

press '-' __1.23__e-¦


press '4' __1.23__e-4¦

leave control 1.23e-4

See Also


StoredContent Property The stored string obtained from the user input string.

Syntax

[VB]

Public Property StoredContent As String

[C#]

public string StoredContent {get; set;}

[Delphi]

property StoredContent: string;

Remarks

Depending on the SaveLiterals property, this is either Content (without literals) or the displayed text including literals.


See Also


StoredEmptyChar Property Character stored in empty mask positions.

Syntax

[VB]

Public Property StoredEmptyChar As Char

[C#]

public char StoredEmptyChar {get; set;}

[Delphi]

property StoredEmptyChar: Char;

Remarks

This property specifies the character stored in blank mask positions (positions left empty by the user) if SaveBlanks = True. Default: '_'.

See Also


GetContent Method· 235

MaskInfo Class Methods

GetContent Method Returns the string containing characters entered by the user, including those on optional positions that were left blank (skipped).

Syntax

[VB]

Public Function GetContent(text As String, textContainsLiterals As Boolean, textContainsBlanks As Boolean, ByVal blankChar As Char) As String

[C#]

public string GetContent(string text, bool textContainsLiterals, bool textContainsBlanks, char blankChar)

[Delphi]

function GetContent (text: String; textContainsLiterals: Boolean; textContainsBlanks: Boolean; ByVal blankChar: Char0: string;


string text Text to parse.

bool textContainsLiterals Same as MaskInfo.SaveLiterals property.

bool textContainsBlanks Same as MaskInfo.SaveBlanks property.

char blankChar Same as MaskInfo.StoredEmptyChar property

Remarks

This method parses the text argument, strips the literals and returns a string containing the characters entered or left blank by the user. Blank characters are represented by StoredEmptyChar. This method performs the same function as the MaskInfo.Content property, but the text for parsing can be arbitrary text, not necessarily the text in the control.

See Also


GetDisplayText Method Returns a string formatted for display using edit mask.

Syntax

[VB]

Public Function GetDisplayText(content As String, skipBlanks As Boolean) As String

[C#]

public string GetDisplayText(string content, bool skipBlanks)

[Delphi]

function GetDisplay (content: string; skipBlanks: Boolean): string;



string content String containing characters entered by the user, including those on optional positions that were left blank (skipped). Blank characters should be represented by StoredEmptyChar. The content can be obtained using MaskInfo.GetContent method.

bool skipBlanks If set to True, the result will omit blank positions. If set to False, the resulting text will contain PromptChar on blank positions (unless ShowLiterals = FreeFormatEntry, in which case this parameter is always considered True).

See Also


GetStoredText Method Returns the string that will be stored in the database, in accordance with current values of SaveLiterals, SaveBlanks and StoredEmptyChar properties.

Syntax

[VB]

Public Function GetStoredText(content As String) As String

[C#]

public string GetStoredText(string content)

[Delphi]

function GetStoredText (content: String): string;


string content String containing characters entered by the user, including those on optional positions that were left blank (skipped). Blank characters should be represented by StoredEmptyChar. The content can be obtained using MaskInfo.GetContent method.

See Also


IsMaskedMode Method Returns True if EditMask is non-empty and the control is in edit mode.

Syntax

[VB]

Public Function IsMaskedMode() As Boolean

[C#]

public bool IsMaskedMode ()

IsValid Method· 237

[Delphi]

function IsMaskedMode (): Boolean;

See Also


IsValid Method Returns True if the input string is valid with respect to the edit mask.

Syntax

[VB]

Public Function IsValid() As Boolean

[C#]

public bool IsValid ()

[Delphi]

function IsValid (): Boolean;

Remarks

Returns True if all required placeholders are filled and all literals are in their respective places.

See Also


ResetContent Method Resets the text to the string representing a DBNull value.

Syntax

[VB]

Public Sub ResetContent()

[C#]

public void ResetContent ()

[Delphi]

procedure ResetContent ()

See Also



PreValidation Class Validating the input string entered by the user, before parsing.

System.Object System.MarshalByRefObject C1.Win.C1Input.PreValidation

Remarks


PreValidation Members PreValidation Properties


CustomPlaceholders User-defined custom placeholder collection for wildcard patterns.


Inherit Manages inheritance of the PreValidation properties from the host control properties.

ItemSeparator String separating list items in PatternString.

PatternString String containing the validation pattern.

RegexOptions Settings affecting regular expression matching.

TrimEnd If True, trailing spaces are removed before validation.

TrimStart If True, leading spaces are removed before validation.

Validation Validation method.

PreValidation Methods

MatchExactList Returns True if the input text matches one of the exact list items specified in PatternString.

MatchRegex Returns True if the input text matches the regular expression pattern specified in PatternString.

MatchWildcardPattern Returns True if the input text matches the specified wildcard pattern passed as argument.

MatchWildcardPatterns Returns True if the input text matches at least one of the wildcard patterns specified in PatternString.

PreValidation Class· 239

Validate Returns True if the text successfully passes validation using the current settings of the PreValidation object.

PreValidation Class Properties

CaseSensitive Property (PreValidation) True if string comparisons are case-sensitive; otherwise, False.

Syntax

[VB]


[C#]


[Delphi]


Remarks

This property affects comparison of the input string with ExactList values, matching it with Wildcard literals and matching it with regular expression pattern.

See Also


CustomPlaceholders Property (PreValidation) User-defined custom placeholder collection for wildcard patterns.

Syntax

[VB]

Public ReadOnly Property CustomPlaceholders As PlaceholderCollection

[C#]

public PlaceholderCollection CustomPlaceholders {get;}

[Delphi]

property CustomPlaceholders: PlaceholderCollection;

Remarks

See CustomPlaceholder class for the description of user-defined wildcards.


See Also



ErrorMessage Property (PreValidation) Error message shown in the standard message box and/or in the exception.

Syntax

[VB]


[C#]


[Delphi]


Remarks

This string is used as the error description if validation fails.


See Also


Inherit Property (PreValidation) Manages inheritance of the PreValidation properties from the host control properties.

Syntax

[VB]

Public Property Inherit As PreValidationInheritFlags

[C#]

public PreValidationInheritFlags Inherit {get; set;}

[Delphi]

property Inherit: PreValidationInheritFlags;

Remarks

This property manages inheritance of CaseSensitive, TrimStart and TrimEnd properties from the control. Default: all properties are inherited

See Also


ItemSeparator Property· 241

ItemSeparator Property String separating list items in PatternString.

Syntax

[VB]

Public Property ItemSeparator As String

[C#]

public string ItemSeparator {get; set;}

[Delphi]

property ItemSeperator: string;

Remarks

Default: "|".


See Also


PatternString Property String containing the validation pattern.

Syntax

[VB]

Public Property PatternString As String

[C#]

public string PatternString {get; set;}

[Delphi]

property PatternString: string;

Remarks

Depending on the value of the Validation property, this property contains either a value list, or a wildcard pattern list, or a regular expression. List items are separated with the string defined in the ItemSeparator property.


See Also



RegexOptions Property Settings affecting regular expression matching.

Syntax

[VB]

Public Property RegexOptions As RegexOptionFlags

[C#]

public RegexOptionFlags RegexOptions {get; set;}

[Delphi]

property RegexOptions: RegexOptionsFlags;

Remarks


See Also


TrimEnd Property (PreValidation) If True, trailing spaces are removed before validation.

Syntax

[VB]


[C#]


[Delphi]


Remarks

Default: True.

See Also


TrimStart Property (PreValidation) If True, leading spaces are removed before validation.

Syntax

[VB]


[C#]


Validation Property (PreValidation)· 243

[Delphi]


Remarks

Default: False.

See Also


Validation Property (PreValidation) Validation method.

Syntax

[VB]

Public Property Validation As PreValidationTypeEnum

[C#]

public PreValidationTypeEnum Validation {get; set;}

[Delphi]

property Validation: PreValidationTypeEnum;

Remarks

See PreValidationTypeEnum for the description of the supported validation methods.


See Also


PreValidation Class Methods

MatchExactList Method Returns True if the input text matches one of the exact list items specified in PatternString.

Syntax

[VB]

Public Function MatchExactList(text As String, errorInfo As ErrorInfo) As Boolean

[C#]

public bool MatchExactList (string text, ErrorInfo errorInfo)

[Delphi]

function MatchExactList (text: String; errorInfo: ErrorInfo): Boolean;



string text The input string to match.

ErrorInfo errorInfo Error information filled in case of failure.

Remarks

If the match is not found and errorInfo is not null, this method fills the errorInfo argument with error information.

See Also


MatchRegex Method Returns True if the input text matches the regular expression pattern specified in PatternString.

Syntax

[VB]

Public Function MatchRegex(text As String, errorInfo As ErrorInfo) As Boolean

[C#]

public bool MatchRegex (string text, ErrorInfo errorInfo)

[Delphi]

function MatchRegex (text: String; errorInfo: ErrorInfo): Boolean;




Remarks

If the string does not match the regular expression and errorInfo is not null, this method fills the errorInfo argument with error information.

See Also


MatchWildcardPattern Method Returns True if the input text matches the specified wildcard pattern passed as argument.

Syntax

[VB]

Public Function MatchWildcardPattern(text As String, pattern As String) As Boolean

[C#]

public bool MatchWildcardPattern (string text, string pattern)

MatchWildcardPatterns Method· 245

[Delphi]

function MatchWildcardPattern (text: String; pattern: String): Boolean;



string pattern The wildcard pattern.

See Also


MatchWildcardPatterns Method Returns True if the input text matches at least one of the wildcard patterns specified in PatternString.

Syntax

[VB]

Public Function MatchWildcardPatterns(text As String, errorInfo As ErrorInfo) As Boolean

[C#]

public bool MatchWildcardPatterns (string text, ErrorInfo errorInfo)

[Delphi]

function MatchWildcardPatterns (text: String; errorInfo: ErrorInfo): Boolean;




Remarks

If the match is not found and errorInfo is not null, this method fills the errorInfo argument with error information.

See Also


Validate Method (PreValidation) Returns True if the text successfully passes validation using the current settings of the PreValidation object.

Syntax

[VB]

Public Function Validate(text As String, errorInfo As ErrorInfo) As Boolean

[C#]

public bool Validate (string text, ErrorInfo errorInfo)


[Delphi]

function Validate (text: String; errorInfo: ErrorInfo): Boolean;


string text The input string to validate.


Remarks

If PatternString property is empty, this method always returns True.

If validation was unsuccessful and errorInfo is not null, this method fills the errorInfo argument with error information.

See Also


PostValidation Class Validating the typed value after parsing, after the input string has been converted to the DataType.

System.Object System.MarshalByRefObject C1.Win.C1Input.PostValidation

Remarks


PostValidation Members PostValidation Properties

AllowDbNull Determines whether it is possible to enter DBNull value in the control.



Inherit Manages inheritance of the PreValidation properties from the host control properties.

Intervals Collection of intervals. The input value must belong to one of these intervals.

Validation Validation method.

Values Predefined values used for matching the input value.

ValuesExcluded List of values that are not permitted as input value.

AllowDbNull Property (PostValidation)· 247

PostValidation Methods

Validate Performs validation using the current settings of the PostValidation object. Returns true if validation was successful.

ValidateValuesAndIntervals Performs validation of the value against the collections of Values, ValuesExcluded and Intervals.

PostValidation Class Properties

AllowDbNull Property (PostValidation) Determines whether it is possible to enter DBNull value in the control.

Syntax

[VB]

Public Property AllowDbNull As Boolean

[C#]

public bool AllowDbNull {get; set;}

[Delphi]

property AllowDbNull: Boolean;

Remarks

If the property is set to True (default), DBNull values are allowed.

See Also


CaseSensitive Property (PostValidation) True if string comparisons are case-sensitive; otherwise, False.

Syntax

[VB]


[C#]


[Delphi]


Remarks

This property affects value comparison if the DataType is String.


See Also


ErrorMessage Property (PostValidation) Error message shown in the standard message box and/or in the exception.

Syntax

[VB]


[C#]


[Delphi]


Remarks

This string is used as the error description if validation fails.


See Also


Inherit Property (PostValidation) Manages inheritance of the PreValidation properties from the host control properties.

Syntax

[VB]

Public Property Inherit As PostValidationInheritFlags

[C#]

public PostValidationInheritFlags Inherit {get; set;}

[Delphi]

property Inherit: PostValidationInheritFlags;

Remarks

This property manages inheritance of the CaseSensitive property from the corresponding property of the control. Default: the property value is inherited

See Also


Intervals Property· 249

Intervals Property Collection of intervals. The input value must belong to one of these intervals.

Syntax

[VB]

Public ReadOnly Property Intervals As ValueIntervalCollection

[C#]

public ValueIntervalCollection Intervals {get;}

[Delphi]

property Intervals: ValueIntervalCollection;

Remarks


See Also


Validation Property (PostValidation) Validation method.

Syntax

[VB]

Public Property Validation As PostValidationTypeEnum

[C#]

public PostValidationTypeEnum Validation {get; set;}

[Delphi]

property Validation: PostValidationTypeEnum;

Remarks

See PostValidationTypeEnum for the description of the supported validation methods.


See Also


Values Property Predefined values used for matching the input value.

Syntax

[VB]

Public Property Values As Array


[C#]

public Array Values {get; set;}

[Delphi]

property Values: Array;

Remarks


See Also


ValuesExcluded Property List of values that are not permitted as input value.

Syntax

[VB]

Public Property ValuesExcluded As Array

[C#]

public Array ValuesExcluded {get; set;}

[Delphi]

property ValuesExcluded: Array;

Remarks


See Also


PostValidation Class Methods

Validate Method (PostValidation) Performs validation using the current settings of the PostValidation object. Returns true if vaidation was successful.

Syntax

[VB]

Public Function Validate(value As Object, errorInfo As ErrorInfo) As Boolean

[C#]

public bool Validate (object value, ErrorInfo errorInfo)

[Delphi]

function Validate (value: Object; errorInfo: ErrorInfo): Boolean;

ValidateValuesAndIntervals Method· 251


object value The value to validate.


Remarks


See Also


ValidateValuesAndIntervals Method Performs validation of the value against the collections of Values, ValuesExcluded and Intervals.

Syntax

[VB]

Public Function ValidateValuesAndIntervals(value As Object, errorInfo As ErrorInfo) As Boolean

[C#]

public bool ValidateValuesAndIntervals (object value, ErrorInfo errorInfo)

[Delphi]

function ValidateValuesAndIntervals (value: Object; errorInfo: ErrorInfo): Boolean;


object value The value to validate.


Remarks

The method returns True if the value belongs to the Values array and does not belong to the ValuesExcluded array, or if the value belongs to one of the intervals defined in the Intervals collection.


See Also



CustomPlaceholder Class Custom user-defined characters (placeholders) used in edit mask (see Edit Mask (page 27)) and in wildcard patterns in pre-validation (see Input string validation (PreValidation) (page 29)).

System.Object C1.Win.C1Input.CustomPlaceholder

CustomPlaceholder Members CustomPlaceholder Properties

CaseSensitive True if string comparison is case-sensitive; otherwise, False.

Excluding Specifies whether the LookupChars are interpreted as allowed or disallowed characters.

LookupChars The list (string) of characters matching the placeholder (see also Excluding).

Optional True if character is optional and can be omitted.

Placeholder The special character used as a user-defined placeholder.

CustomPlaceholder Class Constructors

CustomPlaceholder Constructor Syntax

[VB]

Public Sub New (placeholder As Char, excluding As Boolean, lookupChars As String, caseSensitive As Boolean)

[C#]

public CustomPlaceholder (char placeholder, bool excluding, string lookupChars, bool caseSensitive)

[Delphi]

constructor CustomPlaceholder.Create;


char placeholder The value of the Placeholder property.

bool excluding The value of the Excluding property.

string lookupChars

The value of the LookupChars property.

bool caseSensitive

The value of the CaseSensitive property.

CaseSensitive Property (CustomPlaceholder)· 253

See Also

CustomPlaceholder Class (page 252)

CustomPlaceholder Class Properties

CaseSensitive Property (CustomPlaceholder) True if string comparison is case-sensitive; otherwise, False.

Syntax

[VB]


[C#]


[Delphi]


Remarks

If True (default), the LookupChars characters are matched as is, without case conversion. If False, input characters are matched with LookupChars regardless of case.

See Also


Excluding Property Specifies whether the LookupChars are interpreted as allowed or disallowed characters.

Syntax

[VB]

Public Property Excluding As Boolean

[C#]

public bool Excluding {get; set;}

[Delphi]

property Excluding: Boolean;

Remarks

If this property is set to True, characters listed in LookupChars are excluded from the set of allowed characters (characters matching this placeholder). If this property is set to True (default), characters listed in LookupChars are the allowed (matching) characters.

See Also



LookupChars Property The list (string) of characters matching the placeholder (see also Excluding).

Syntax

[VB]

Public Property LookupChars As String

[C#]

public string LookupChars {get; set;}

[Delphi]

property LookingChars: string;

Remarks

This property specifies the characters allowed for input on a position occupied by this custom placeholder character. Comparison is case-sensitive or case-insensitive depending on the CaseSensitive property.

See Also


Optional Property True if character is optional and can be omitted.

Syntax

[VB]

Public Property Optional As Boolean

[C#]

public bool Optional {get; set;}

[Delphi]

property Optional: Boolean;

Remarks

This property is used by edit mask and wildcard-based pre-validation. If Optional = True, the user can leave this placeholder blank in the edit mask and omit it in a string validated with a wildcard pattern.

See Also


Placeholder Property The special character used as a user-defined placeholder.

Syntax

[VB]

Public Property Placeholder As Char

DropDownForm Class· 255

[C#]

public char Placeholder {get; set;}

[Delphi]

property Placeholder: Char;

See Also


DropDownForm Class Base class for custom dropdown forms.

System.Object System.MarshalByRefObject System.ComponentModel.Component System.Windows.Forms.Control System.Windows.Forms.ScrollableControl System.Windows.Forms.ContainerControl System.Windows.Forms.Form C1.Win.C1Input.DropDownForm

DropDownForm Members DropDownForm Properties

BorderStyle Determines border style of the dropdown.

DropDownAlign Determines the alignment of the dropdown form relative to the owner control.

FocusControl Determines the control in the form that receives focus when the form opens.

Options Determines option flags for dropdown form behavior.

OwnerControl Returns the control that owns the dropdown form.

DropDownForm Events

CancelChanges Occurs when the dropdown editing is cancelled.

Open Occurs when the dropdown form is opened, before it is shown to the user.

OwnerControlTextChanged Occurs when the Text property of OwnerControl changes.

OwnerControlValueChanged Occurs when the Value property of OwnerControl changes.

PostChanges Occurs when the dropdown form is closed and the changes made by the user in the form must be saved in the control.


DropDownForm Class Properties

BorderStyle Property (DropDownForm) Determines border style of the dropdown.

Syntax

[VB]

Public Property BorderStyle As BorderStyle

[C#]

public BorderStyle BorderStyle {get; set;}

[Delphi]

property BorderStyle: BorderStyle;

See Also

DropDownForm Class (page 255)

DropDownAlign Property Determines the alignment of the dropdown form relative to the owner control.

Syntax

[VB]

Public Property DropDownAlign As DropDownFormAlignmentEnum

[C#]

public DropDownFormAlignmentEnum DropDownAlign {get; set;}

[Delphi]

property DropDownAlign: DropDownFormAlignmentEnum;

Remarks

See DropDownFormAlignmentEnum for the list of available options.

See Also


FocusControl Property Determines the control in the form that receives focus when the form opens.

Syntax

[VB]

Public Property FocusControl As Control

[C#]

public Control FocusControl {get; set;}

Options Property· 257

[Delphi]

property FocusControl: Control;

Remarks

If this property is set to null, the form itself receives focus.

See Also


Options Property Determines option flags for dropdown form behavior.

Syntax

[VB]

Public Property Options As DropDownFormOptionsFlags

[C#]

public DropDownFormOptionsFlags Options {get; set;}

[Delphi]

property Options: DropDownFormOptionsFlags;

Remarks

See DropDownFormOptionsFlags for the list of available options.

See Also


OwnerControl Property Returns the control that owns the dropdown form.

Syntax

[VB]

Public Property OwnerControl As DropDownForm

[C#]

public DropDownForm OwnerControl {get; set;}

[Delphi]

property OwnerControl: DropDownForm;

See Also



DropDownForm Class Events

CancelChanges Event Occurs when the dropdown editing is canceled. Use this event to cancel changes made to the control's Value in the dropdown form, to restore the previous value, when the form is closed with cancellation (for example, the Esc key pressed).

Syntax

[VB]

Public Event CancelChanges As EventHandler

[C#]

public event EventHandler CancelChanges

[Delphi]

property CancelChanges: EventHandler;

See Also


Open Event Occurs when the dropdown form is opened, before it is shown to the user. Use this event to initialize the form.

Syntax

[VB]

Public Event Open As EventHandler

[C#]

public event EventHandler Open

[Delphi]

property Open: EventHandler;

See Also


OwnerControlTextChanged Event Occurs when the Text property of OwnerControl changes.

Syntax

[VB]

Public Event OwnerControlTextChanged As EventHandler

[C#]

public event EventHandler OwnerControlTextChanged

OwnerControlValueChanged Event· 259

[Delphi]

property OwnerControlTextChanged: EventHandler;

See Also


OwnerControlValueChanged Event Occurs when the Value property of OwnerControl changes.

Syntax

[VB]

Public Event OwnerControlValueChanged As EventHandler

[C#]

public event EventHandler OwnerControlValueChanged

[Delphi]

property OwnerControlValueChanged: EventHandler;

See Also


PostChanges Event Occurs when the dropdown form is closed and the changes made by the user in the form must be saved in the control. Use this event to change the control's Value if it has not been changed before.

Syntax

[VB]

Public Event PostChanges As EventHandler

[C#]

public event EventHandler PostChanges

[Delphi]

property PostChanges: EventHandler;

See Also



PlaceholderCollection Class A collection of CustomPlaceholder objects.

System.Object System.Collections.CollectionBase C1.Win.C1Input.PlaceholderCollection

PlaceholderCollection Members PlaceholderCollection Methods (methods inherited from CollectionBase are not shown)

Add Adds a new special character to the collection.

Contains Determines whether a character is in the placeholder collection.

CopyTo Copies elements of the collection to an array starting at a particular array index.

GetItem Returns the CustomPlaceholder object corresponding to the character argument, or null if it does not belong to the collection.

IndexOf Returns the index of a character in the placeholder collection, or –1 if it does not belong to the collection.

Insert Inserts a new special character to the collection at the specified position.

Remove Removes a specific character from the collection.

PlaceholderCollection Class Methods

Add Method (PlaceholderCollection) Adds a new special character to the collection.

Syntax

[VB]

Public Sub Add(cph As CustomPlaceholder)

[C#]

public void Add(CustomPlaceholder cph)

[Delphi]

procedure Add (cph: CustomPlaceholder);

Contains Method (PlaceholderCollection)· 261


CustomPlaceholder cph

The CustomPlaceholder to add.

See Also

PlaceholderCollection Class (page 259)

Contains Method (PlaceholderCollection) Determines whether a character is in the placeholder collection.

Syntax

[VB]

Public Function Contains(placeholder As Char) As Boolean

[C#]

public bool Contains (char placeholder)

[Delphi]

function Contains (pleaceholder: Char): Boolean;


char placeholder The character argument.

See Also


CopyTo Method (PlaceholderCollection) Copies elements of the collection to an array starting at a particular array index.

Syntax

[VB]

Public Sub CopyTo(array As CustomPlaceholder(), index As Integer)

[C#]

public void CopyTo(CustomPlaceholder[] array, int index)

[Delphi]

procedure CopyTo (array: CustomPlaceholder; index: Integer);


CustomPlaceholder[] array

The one-array that is the destination of the elements copied from the collection. The array must have zero-based indexing.

int index The zero-based index in array at which copying begins.

See Also



IndexOf Method (PlaceholderCollection) Returns the index of a character in the placeholder collection, or –1 if it does not belong to the collection.

Syntax

[VB]

Public Function IndexOf(placeholder As Char) As Integer

[C#]

public int IndexOf (char placeholder)

[Delphi]

function IndexOf (pleaceholder: Char): Integer;



See Also


Insert Method (PlaceholderCollection) Inserts a new special character to the collection at the specified position.

Syntax

[VB]

Public Sub Insert(index As Integer, cph As CustomPlaceholder)

[C#]

public void Insert(int index, CustomPlaceholder cph)

[Delphi]

procedure Insert index: Integer; cph: CustomPlaceholder);


int index The zero-based index at which CustomPlaceholder should be inserted.

CustomPlaceholder cph

The CustomPlaceholder to insert.

See Also


Remove Method (PlaceholderCollection)· 263

Remove Method (PlaceholderCollection) Removes a specific character from the collection.

Syntax

[VB]

Public Sub Remove(placeholder As Char)

[C#]

public void Remove(char placeholder)

[Delphi]

procedure Remove (placeholder: Char);


char placeholder The character to remove from the collection.

See Also


GetItem Method (PlaceholderCollection) Returns the CustomPlaceholder object corresponding to the character argument, or null if it does not belong to the collection.

Syntax

[VB]

Public Function GetItem(placeholder As Char) As CustomPlaceholder

[C#]

public CustomPlaceholder GetItem (char placeholder)

[Delphi]

function GetItem (placeholder: Char): CustomPlaceholder;



See Also



ValueInterval Class An interval in a collection of intervals of possible values used in post-validation.

System.Object C1.Win.C1Input.ValueInterval

Remarks


ValueInterval Members ValueInterval Properties

DataType The type of lower and upper bounds (taken from the control’s DataType).

IncludeMax If True (default), the upper bound is included (<=).

IncludeMin If True (default), the lower bound is included (>=).

MaxValue Upper bound.

MinValue Lower bound.

UseMaxValue If False (default), the upper bound is positive infinity.

UseMinValue If False (default), the lower bound is negative infinity.

ValueInterval Class Constructors

ValueInterval Constructor Syntax

[VB]

Public Sub New (minValue As Object, maxValue As Object, includeMin As Boolean, includeMax As Boolean)

[C#]

public ValueInterval (object minValue, object maxValue, bool includeMin, bool includeMax)

[Delphi]

constructor ValueInterval.create;


object minValue MinValue property value.

object maxValue MaxValue property value.

DataType Property (ValueInterval)· 265


bool includeMin IncludeMin property value.

bool includeMax IncludeMax property value.

ValueInterval Class Properties

DataType Property (ValueInterval) The type of lower and upper bounds (taken from the control’s DataType).

Syntax

[VB]

Public Property DataType As Type

[C#]

public Type DataType {get; set;}

[Delphi]

property DataType: Type;

See Also

ValueInterval Class (page 263)

IncludeMax Property If True (default), the upper bound is included (<=).

Syntax

[VB]

Public Property IncludeMax As Boolean

[C#]

public bool IncludeMax {get; set;}

[Delphi]

property IncludeMax: Boolean;

See Also


IncludeMin Property If True (default), the lower bound is included (>=).

Syntax

[VB]

Public Property IncludeMin As Boolean


[C#]

public bool IncludeMin {get; set;}

[Delphi]

property IncludeMin: Boolean;

See Also


MaxValue Property Upper bound.

Syntax

[VB]

Public Property MaxValue As Object

[C#]

public object MaxValue {get; set;}

[Delphi]

property MaxValue: Object;

See Also


MinValue Property Lower bound.

Syntax

[VB]

Public Property MinValue As Object

[C#]

public object MinValue {get; set;}

[Delphi]

property MinValue: Object;

See Also


UseMaxValue Property If False (default), the upper bound is positive infinity.

Syntax

[VB]

Public Property UseMaxValue As Boolean

UseMinValue Property· 267

[C#]

public bool UseMaxValue {get; set;}

[Delphi]

property UseMaxValue: Boolean;

See Also


UseMinValue Property If False (default), the lower bound is negative infinity.

Syntax

[VB]

Public Property UseMinValue As Boolean

[C#]

public bool UseMinValue {get; set;}

[Delphi]

property UseMinValue: Boolean;

See Also


ValueIntervalCollection Class A collection of ValueInterval objects used by a PostValidation object. The collection is used if the Validation = PostValidationTypeEnum.ValuesAndIntervals or if the user calls the ValidateValuesAndIntervals method.

System.Object System.Collections.CollectionBase C1.Win.C1Input.ValueIntervalCollection


ValueIntervalCollection Members ValueIntervalCollection Properties (properties inherited from CollectionBase are not shown)

Item Gets the collection element at the specified index.

ValueIntervalCollection Methods (methods inherited from CollectionBase are not shown)

Add Adds a new value interval to the collection.

AddRange Adds the elements of an array to the end of the collection.


Contains Returns True if the collection contains the specific value interval, False otherwise.

CopyTo Copies elements of the collection to an array starting at a particular array index.

IndexOf Determines the index of a specific value interval in the collection, return -1 if this item not found.

Insert Inserts a new value interval to the collection at the specified position.

Remove Removes a specific value interval from the collection.

ValueIntervalCollection Class Constructor

ValueIntervalCollection Constructor Syntax

[VB]

Public Sub New ()

[C#]

public ValueIntervalCollection

[Delphi]

constructor ValueIntervalCollection.create;

See Also

ValueIntervalCollection Class (page 267)

ValueIntervalCollection Class Properties

Item Property (ValueIntervalCollection) Gets the collection element at the specified index.

Syntax

[VB]

Public Property Item As ValueInterval

[C#]

public ValueInterval this[int index] {get; set;}

[Delphi]

property Item: ValueInterval;

See Also


Add Method (ValueIntervalCollection)· 269

ValueIntervalCollection Class Methods

Add Method (ValueIntervalCollection) Adds a new value interval to the collection.

Syntax

[VB]

Public Sub Add(vi As ValueInterval)

[C#]

public void Add(ValueInterval vi)

[Delphi]

procedure Add(vi: ValueInterval);


ValueInterval vi The ValueInterval to add.

See Also


AddRange Method (ValueIntervalCollection) Adds the elements of an array to the end of the collection.

Syntax

[VB]

Public Sub AddRange(c As ValueInterval())

[C#]

public void AddRange (ValueInterval[] c)

[Delphi]

procedure AddRange (c: ValueInterval);


ValueInterval[] c The array whose elements should be added to the end of the collection.

See Also



Contains Method (ValueIntervalCollection) Returns True if the collection contains the specific value interval, False otherwise.

Syntax

[VB]

Public Function Contains(vi As ValueInterval) As Boolean

[C#]

public bool Contains(ValueInterval vi)

[Delphi]

function Contains(vi: ValueInterval): Boolean;


ValueInterval vi The ValueInterval to locate in the collection.

See Also


CopyTo Method (ValueIntervalCollection) Copies elements of the collection to an array starting at a particular array index.

Syntax

[VB]

Public Sub CopyTo(array As ValueInterval(), index As Integer)

[C#]

public void CopyTo(ValueInterval[] array, int index)

[Delphi]

procedure CopyTo(array: ValueInterval);


ValueInterval[] array

The one-array that is the destination of the elements copied from the collection. The array must have zero-based indexing.

int index The zero-based index in array at which copying begins.

See Also


IndexOf Method (ValueIntervalCollection)· 271

IndexOf Method (ValueIntervalCollection) Determines the index of a specific value interval in the collection, return -1 if this item not found.

Syntax

[VB]

Public Function IndexOf(vi As ValueInterval) As Integer

[C#]

public int IndexOf(ValueInterval vi)

[Delphi]

function IndexOf(vi: ValueInteger): Integer;


ValueInterval vi The ValueInterval to locate in the collection.

See Also


Insert Method (ValueIntervalCollection) Inserts a new value interval to the collection at the specified position.

Syntax

[VB]

Public Sub Insert(index As Integer, vi As ValueInterval)

[C#]

public void Insert(int index, ValueInterval vi)

[Delphi]

procedure Insert(index: Integer; vi: ValueInterval);


int index The zero-based index at which ValueInterval should be inserted.

ValueInterval vi The ValueInterval to insert.

See Also



Remove Method (ValueIntervalCollection) Removes a specific value interval from the collection.

Syntax

[VB]

Public Sub Remove(vi As ValueInterval)

[C#]

public void Remove(ValueInterval vi)

[Delphi]

procedure Remove(vi: ValueInterval);


ValueInterval vi The ValueInterval to remove from the collection.

See Also


ErrorInfo Class Settings affecting error handling.

System.Object C1.Win.C1Input.ErrorInfo

Remarks


ErrorInfo Members ErrorInfo Properties

BeepOnError If True, the control beeps signaling an error. Default: False.

CanLoseFocus Determines whether or not the control is allowed to lose focus after the error.

ErrorAction Enumerated value that determines what action is performed on the control value when an error occurs.


ErrorMessageCaption The text to display in the title bar of the error message box.


BeepOnError Property· 273

InnerException Run-time-only read-only property returning the original exception object that caused the error.

ShowErrorMessage If True (default), the standard error message is shown.

ValueOnError Value used to reset the control if ErrorAction = SetValueOnError.

ValueOnErrorIsDbNull Boolean property used to set ValueOnError to DBNull (only necessary at design time).

ErrorInfo Class Properties

BeepOnError Property If True, the control beeps signaling an error. Default: False.

Syntax

[VB]

Public Property BeepOnError As Boolean

[C#]

public bool BeepOnError {get; set;}

[Delphi]

property BeepOnError: Boolean;

Remarks


See Also


CanLoseFocus Property Determines whether or not the control is allowed to lose focus after the error.

Syntax

[VB]

Public Property CanLoseFocus As Boolean

[C#]

public bool CanLoseFocus {get; set;}

[Delphi]

property CanLoseFocus: Boolean;


Remarks

If True, the control is allowed to lose focus regardless of the error. This property is False by default, meaning that the control will stay in focus until the error is corrected. Note that setting ErrorAction to SetValueOnError or ResetValue allow the user to leave the control after error by resetting its value.


See Also


ErrorAction Property Enumerated value that determines what action is performed on the control value when an error occurs.

Syntax

[VB]

Public Property ErrorAction As ErrorActionEnum

[C#]

public ErrorActionEnum ErrorAction {get; set;}

[Delphi]

property ErrorAction: ErrorActionEnum;

Remarks

ErrorAction = None (default) means that Value is not changed, remains as it was before the unsuccessful value update. If ErrorAction = SetValueOnError, control’s Value is set to the value specified in the ValueOnError property of the ErrorInfo class. If ErrorAction = ResetValue, control’s Value is set to the last value the control had before it entered edit mode. Setting ErrorAction = ThrowException interrupts execution and throws an exception, ValidationException.


See Also


ErrorMessage Property Error message shown in the standard message box and/or in the exception.

Syntax

[VB]


[C#]


[Delphi]


ErrorMessageCaption Property· 275

Remarks


See Also


ErrorMessageCaption Property The text to display in the title bar of the error message box.

Syntax

[VB]

Public Property ErrorMessageCaption As String

[C#]

public string ErrorMessageCaption {get; set;}

[Delphi]

property ErrorMessageCaption: string;

See Also


ErrorProvider Property (ErrorInfo) Gets or sets an ErrorProvider object used to indicate error state of the control.

Syntax

[VB]


[C#]


[Delphi]

property ErrorProvider: ErrorProvider

Remarks

If this property is set, the specified error provider is used to signal error conditions occurring in the control (ErrorProvider.SetControl method is used to show errors in the error provider). Following error conditions are shown:

• Parsing or validating the value entered by the user fails.

• Value obtained from the database does not conform to the edit mask.

• An exception occurs formatting the value obtained from the database.

• Formatting the text obtained from the database is done in the Formatting event, and fails (Formatting event returns Succeeded = False).

See Also

ErrorInfo Property (page 169)


InnerException Property (ErrorInfo) Run-time-only read-only property returning the original exception object that caused the error.

Syntax

[VB]

Public ReadOnly Property InnerException As Exception

[C#]

public Exception InnerException {get;}

[Delphi]

property InnerException: Exception;

See Also


ShowErrorMessage Property If True (default), the standard error message is shown.

Syntax

[VB]

Public Property ShowErrorMessage As Boolean

[C#]

public bool ShowErrorMessage {get; set;}

[Delphi]

property ShowErrorMessage: Boolean;

Remarks


See Also


ValueOnError Property Value used to reset the control if ErrorAction = SetValueOnError.

Syntax

[VB]

Public Property ValueOnError As Object

[C#]

public object ValueOnError {get; set;}

[Delphi]

property ValueOnError: Object;

ValueOnErrorIsDbNull Property· 277

Remarks


See Also


ValueOnErrorIsDbNull Property Boolean property used to set ValueOnError to DBNull (only necessary at design time).

Syntax

[VB]

Public Property ValueOnErrorIsDbNull As Boolean

[C#]

public bool ValueOnErrorIsDbNull {get; set;}

[Delphi]

property ValueOneErrorIsDbNull: Boolean;

Remarks


See Also


UIStrings Class A collection of user interface strings that can be localized (customized) at design time and at run time.

System.Object C1.Util.UIStrings

UIStrings Members UIStrings Properties

Item Gets or sets the string shown to the end user.

UIStrings Class Properties

Item Property (UIStrings) Gets or sets the string shown to the end user. The string is indexed by a key. For example, the default value for this string can be used as the string's key.

Syntax

[VB]

Public Property Default Item As String(key As Object)


[C#]

public string this[object key] {get; set;}

[Delphi]

property Item: string;

See Also

UIStrings Class (page 277)

C1Input Enumeration Reference DateTimeStyleFlags Enumeration

Used by ParseInfo.DateTimeStyle property.

Syntax

[VB]

Public Enum DateTimeStyleFlags

[C#]

public sealed enum DateTimeStyleFlags : System.Enum

[Delphi]

type DateTimeStyleFlags = (None, AllowInnerWhite, AllowLeadingWhite, AllowTrailingWhite, AllowWhiteSpaces, NoCurrentDateDefault);

Member name Description

None Indicates that the default formatting options must be used.

AllowInnerWhite Indicates that extra white space characters in the middle of the string must be ignored during parsing, except if those white space characters occur in the format patterns.

AllowLeadingWhite Indicates that leading white space characters must be ignored during parsing, except if those white space characters occur in the format patterns.

AllowTrailingWhite Indicates that trailing white space characters must be ignored during parsing, except if those white space characters occur in the format patterns.

AllowWhiteSpaces Indicates that extra white space characters anywhere in the string must be ignored during parsing, except if those white space characters occur in the format patterns. This value is a combination of the AllowLeadingWhite, AllowTrailingWhite, and AllowInnerWhite values.

NoCurrentDateDefault Indicates that, if the parsed string contains only the time and not the date, the parsing methods assume the Gregorian date with year = 1, month = 1, and day = 1. If this value is not used, the current date is assumed.

DaylightTimeAdjustmentEnum Enumeration· 279

DaylightTimeAdjustmentEnum Enumeration Used by C1Label.DaylightTimeAdjustment and C1TextBox.DaylightTimeAdjustment properties.

Syntax

[VB]

Public Enum DaylightTimeAdjustmentEnum

[C#]

public sealed enum DaylightTimeAdjustmentEnum : System.Enum

[Delphi]

type DaylightTimeAdjustmentEnum = (NoAdjustments, AdvanceGMTOffsetForTheDayightSavingTime, SetGMTOffsetBackForTheStandardTime);


NoAdjustments No daylight-saving time adjustments.

AdvanceGMTOffsetForTheDaylightSavingTime Use this option if the GMTOffset property corresponds to the standard time offset. For the daylight-saving time GMTOffset should be advanced by an hour.

SetGMTOffsetBackForTheStandardTime Use this option if the GMTOffset property is set to the daylight time offset. So, for the standard time it should be set back by an hour.

DropDownControlButtonFlags Enumeration Used by C1DropDownControl.VisibleButtons properties.

Syntax

[VB]

Public Enum DropDownControlButtonFlags

[C#]

public sealed enum DropDownControlButtonFlags : System.Enum

[Delphi]

type DropDownControlButtonFlags = (UpDown, DropDown, Modal);


UpDown Show up/down buttons.

DropDown Show dropdown button.

Modal Show button to start a modal dialog.


DropDownFormAlignmentEnum Enumeration Used by DropDownForm.DropDownAlign and C1DropDownControl.DropDownFormAlign properties.

Syntax

[VB]

Public Enum DropDownFormAlignmentEnum

[C#]

public sealed enum DropDownFormAlignmentEnum : System.Enum

[Delphi]

type DropDownFormAlignmentEnum = (Default, Center, Left, Right);


Default In a C1DropDownControl, the alignment of the dropdown form is determined by the DropDownAlign property of the drop down form.

Center Center alignment.

Left Left alignment..

Right Right alignment.

DropDownFormOptionsFlags Enumeration Used by DropDownForm.Options property.

Syntax

[VB]

Public Enum DropDownFormOptionsFlags

[C#]

public sealed enum DropDownFormOptionsFlags : System.Enum

[Delphi]

type DropDownFormOptionsFlags = (AlwaysPostChanges, AutoResize, FixedHeight, FixedWidth, FixedSize, NoCancelOnEscape, NoPostOnEnter)


AlwaysPostChanges If this flag is set, the changes to the control Value can only be cancelled explicitly, with Esc key or using the CloseDropDown method, and implicit cancellation (when the form is closed because it loses focus) is disabled.

AutoResize If set, the dropdown form width is automatically adjusted to the width of the owner control before the form is shown.

ErrorActionEnum Enumeration· 281


FixedHeight The end users are not allowed to change the height of the dropdown form resizing it.

FixedWidth The end users are not allowed to change the width of the dropdown form resizing it.

FixedSize = FixedWidth + FixedHeight

NoCancelOnEscape If this flag is set, pressing the Esc key does not close the form.

NoPostOnEnter If this flag is set, pressing the Enter key does not close the form.

ErrorActionEnum Enumeration Used by ErrorInfo.ErrorAction property.

Syntax

[VB]

Public Enum ErrorActionEnum

[C#]

public sealed enum ErrorActionEnum : System.Enum

[Delphi]

type ErrorActionEnum = (None, SetValueOnError, ResetValue, ThrowException);


None Control value remains as the user typed it.

SetValueOnError Control value is set to ValueOnError.

ResetValue Control value is reset to the value control had before entering edit mode.

ThrowException Control value is reset to the value control had before entering edit mode, and an exception is thrown.

ErrorReasonEnum Enumeration Used by ValidationErrorEventArgs.Reason and ValidationException.Reason properties.

Syntax

[VB]

Public Enum ErrorReasonEnum

[C#]

public sealed enum ErrorReasonEnum : System.Enum

[Delphi]

type ErrorReasonEnum = (NoErrors, DataSourceError, EditMaskError, PreValidationError, ParsingError, PostValidationError);



NoErrors All validation checks were successful.

DataSourceError Value rejected by the data source, setting the data source field to that value failed.

EditMaskError Value does not match the edit mask.

PreValidationError Value was rejected before parsing (in PreValidation).

ParsingError Parsing failed.

PostValidationError Value rejected after parsing (in PostValidation).

FormatInfoInheritFlags Enumeration Used by FormatInfo.Inherit property.

Syntax

[VB]

Public Enum FormatInfoInheritFlags

[C#]

public sealed enum FormatInfoInheritFlags: System.Enum

[Delphi]

type FormatInfoInheritFlags = (None, FormatType, CustomFormat, NullText, EmptyAsNull,TrimStart,TrimEnd,All);


None Indicates that none of the properties are inherited from the control.

FormatType Indicates that the FormatType property is inherited from the control.

CustomFormat Indicates that the CustomFormat property is inherited from the control.

NullText Indicates that the NullText property is inherited from the control.

EmptyAsNull Indicates that the EmptyAsNull property is inherited from the control.

TrimStart Indicates that the TrimStart property is inherited from the control.

TrimEnd Indicates that the TrimEnd property is inherited from the control.

All Indicates that values of FormatType, CustomFormat, NullText, EmptyAsNull, TrimStart, TrimEnd properties are inherited from the control.

FormatTargetEnum Enumeration· 283

FormatTargetEnum Enumeration Used by FormatEventArgs.Target property.

Syntax

[VB]

Public Enum FormatTargetEnum

[C#]

public sealed enum FormatTargetEnum : System.Enum

[Delphi]

type FormatTargetEnum = (ForDisplay, ForEdit);


ForDisplay Formatting (or Formatted) event was called while the control is not in edit mode.

ForEdit Formatting (or Formatted) event was called while the control is in edit mode.

FormatTypeEnum Enumeration Used by FormatType property.

See Format types (page 17) for the list of available options.

Syntax

[VB]

Public Enum FormatTypeEnum

[C#]

public sealed enum FormatTypeEnum : System.Enum

[Delphi]

type FormatTypeEnum = (Currency, CustomFormat, DateAndTimeGMT, DateTimeSortable, DefaultFormat, FixedPoint, GeneralDate, GeneralNumber, GMTSortable, Hexadecimal, Integer, LongDate, LongDateLongTime, LongDateShortTime, LongDateTimeGMT, LongTime, MediumDate, MediumTime, MonthAndDay, OnOff, Percent, RoundTrip, Scientific, ShortDate, ShortDateLongTime, ShortDateShortTime, ShortTime, StandardNumber, TrueFalse, UseEvent, YearAndMonth, YesNo);

InitialSelectionEnum Enumeration Used by C1TextBox.InitialSelection property.

Syntax

[VB]

Public Enum InitialSelectionEnum


[C#]

public sealed enum InitialSelectionEnum : System.Enum

[Delphi]

type InitialSelectionEnum = (CareAtEnd, CareAtStart, SelectAll);


SelectAll The whole text is selected.

CaretAtStart Nothing selected, the caret is moved at the beginning of the text.

CaretAtEnd Nothing selected, the caret is moved at the end of the text.

MaskInfoInheritFlags Enumeration Used by MaskInfo.Inherit property.

Syntax

[VB]

Public Enum MaskInfoInheritFlags

[C#]

public sealed enum MaskInfoInheritFlags : System.Enum

[Delphi]

type MaskInfoInheritFlags = (None, CaseSensitive, EmptyAsNull, All);



CaseSensitive Indicates that the CaseSensitive property is inherited from the control.

EmptyAsNull Indicates that the EmptyAsNull property is inherited from the control.

All Indicates that values of CaseSensitive, EmptyAsNull, and TrimEnd properties are inherited from the control.

NavigatorButtonEnum Enumeration Syntax

[VB]

Public Enum NavigatorButtonEnum

[C#]

public sealed enum NavigatorButtonEnum : System.Enum

[Delphi]

type NavigatorButtonEnum = (First, Previous, Next, Last, Add, Delete, Edit, Apply, Cancel, Update, Refresh);

NavigatorButtonFlags Enumeration· 285


First First button.

Previous Previous button.

Next Next button.

Last Last button.

Add Add button.

Delete Delete button.

Edit Edit button.

Apply Apply button.

Cancel Cancel button.

Update Update button.

Refresh Refresh button.

Remarks

Related Topic: NavigatorButtonFlags

NavigatorButtonFlags Enumeration Syntax

[VB]

Public Enum NavigatorButtonFlags

[C#]

public sealed enum NavigatorButtonFlags : System.Enum

[Delphi]

type NavigatorButtonFlags = (None, First, Previous, Next, Last, Add, Delete, Edit, Apply, Cancel, Update, Refresh, Navigation, All);


None No buttons.

First Moves to the first row.

Previous Moves to the previous row.

Next Moves to the next row.

Last Moves to the last row.

Add Adds a new row to the table. Calls CurrencyManager.AddNew.

Delete Deletes the current row. Calls CurrencyManager.RemoveAt(currentRow).

Edit Fires the Editing event. You can put any code in that event, but the intent is to starts editing the current row, put it in edit mode.



Apply Ends edit mode for the current row. Calls CurrencyManager.EndCurrentEdit.

Cancel Cancels (reverts) modifications in the current row. Calls CurrencyManager.CancelCurrentEdit.

Update Fires the UpdateData event. You can put any code in that event, but the intent is to update the database, send the modifications to the database. Before firing the UpdateData event, calls CurrencyManager.EndCurrentEdit.

Refresh Fires the RefreshData event. You can put any code in that event, but the intent is to re-fetch your data from the database (canceling all modifications done by the user). Before firing the RefreshData event, calls CurrencyManager.CancelCurrentEdit. After firing the RefreshData event, calls CurrencyManager.Refresh.

Navigation First + Previous + Next + Last

All All buttons.

NavigatorButtonStyleEnum Enumeration Used by C1DbNavigator.ButtonStyle property.

Syntax

[VB]

Public Enum NavigatorButtonStyleEnum

[C#]

public sealed enum NavigatorButtonStyleEnum : System.Enum

[Delphi]

type NavigatorButtonStyleEnum = (Flat, Standard);


Flat Flat buttons showing "mouse hover".

Standard Standard 3D-buttons.

NavigatorButtonTextAlignEnum Enumeration Used by C1DbNavigator.ButtonTextAlign property.

Syntax

[VB]

Public Enum NavigatorButtonTextAlignEnum

[C#]

public sealed enum NavigatorButtonTextAlignEnum : System.Enum

NumberStyleFlags Enumeration· 287

[Delphi]

type NavigatorButtonTextAlignEnum = (Right, Underneath);


Right Text appears to the right of the image.

Underneath Text appears underneath the image.

NumberStyleFlags Enumeration Used by ParseInfo.NumberStyle property.

Syntax

[VB]

Public Enum NumberStyleFlags

[C#]

public sealed enum NumberStyleFlags : System.Enum

[Delphi]

type NumberStyleFlags = (None, AllowCurrencySymbol, AllowDecimalPoint, AllowExponent, AllowHexSpecifier, AllowLeadingSign, AllowLeadingWhite, AllowParentheses, AllowThousands, AllowTrailingSign, AllowTrailingWhite, Any, Currency, Float, HexNumber, Integer);


None Indicates that none of the bit styles are allowed.

AllowCurrencySymbol Indicates that the numeric string is parsed as currency if it contains a currency symbol; otherwise, it is parsed as a number.

AllowDecimalPoint Indicates that the numeric string can have a decimal point.

AllowExponent Indicates that the numeric string can be in exponential notation.

AllowHexSpecifier Indicates that the numeric string can have notation that signifies that the number is hexadecimal. Valid hexadecimal values include the numeric digits 0-9 and the hexadecimal digits A-F and a-f. Hexadecimal values can be left-padded with zeros. Strings parsed using this style are not permitted to be prefixed with "0x".

AllowLeadingSign Indicates that the numeric string can have a leading sign.

AllowLeadingWhite Indicates that a leading white-space character is ignored during parsing.

AllowParentheses Indicates that the numeric string can have one pair of parentheses enclosing the number.

AllowThousands Indicates that the numeric string can have group separators.

AllowTrailingSign Indicates that the numeric string can have a trailing sign.

AllowTrailingWhite Indicates that trailing white-space character must be ignored during parsing.



Any Indicates that all the AllowXXX bit styles are used.

Currency Indicates all styles except AllowExponent and AllowHexSpecifier.

Float Indicates that the AllowLeadingWhite, AllowTrailingWhite, AllowLeadingSign, AllowDecimalPoint, and AllowExponent styles are used.

HexNumber Indicates that the AllowLeadingWhite, AllowTrailingWhite, and AllowHexSpecifier styles are used.

Integer Indicates that the AllowLeadingWhite, AllowTrailingWhite, and AllowLeadingSign styles are used.

Number Indicates that the AllowLeadingWhite, AllowTrailingWhite, AllowLeadingSign, AllowTrailingSign, AllowDecimalPoint, and AllowThousands styles are used.

NavigatorVerticalAlignEnum Enumeration Used by C1DbNavigator.VerticalAlign property.

Syntax

[VB]

Public Enum NavigatorVerticalAlignEnum

[C#]

public sealed enum NavigatorVerticalAlignEnum : System.Enum

[Delphi]

type NavigatorVerticalAlignEnum = (Top, middle, Bottom);


Top Buttons are aligned with the top of the control.

Middle Buttons are aligned with the center of the control.

Bottom Buttons are aligned with the bottom of the control.

NumericInputKeyFlags Enumeration Used by C1TextBox.NumericInputKeys property.

Syntax

[VB]

Public Enum NumericInputKeyFlags

[C#]

public sealed enum NumericInputKeyFlags : System.Enum

ParseInfoInheritFlags Enumeration· 289

[Delphi]

type NumericInputKeyFlags = (F2, F3, F4, F9, Minus, Plus, Decimal, X, Standard);


F2 Indicates that F2 enters negative infinity (-Infinity).

F3 Indicates that F3 enters positive infinity (+Infinity).

F4 Indicates that F4 enters the "not a number" value (NaN).

F9 Indicates that F9 toggles the sign of the displayed number.

Minus Indicates that '-' makes the displayed number negative.

Plus Indicates that '+' makes the displayed number positive.

Decimal Indicates that Decimal key enters a decimal separator regardless of culture settings.

X Indicates that the X key starts entry of the exponent part in scientific-notation numbers.

Standard This value is a combination of the F9, Minus, Plus, Decimal, and X values.

ParseInfoInheritFlags Enumeration Used by ParseInfo.Inherit property.

Syntax

[VB]

Public Enum ParseInfoInheritFlags

[C#]

public sealed enum ParseInfoInheritFlags : System.Enum

[Delphi]

type ParseInfoInheritFlags = (None, CaseSensitive, FormatType, CustomFormat, NullText, EmptyAsNull, TrimStart, TrimEnd, All);



CaseSensitive Indicates that the value of the CaseSensitive property is inherited from the control.

FormatType Indicates that the value of the FormatType property is inherited from the control.

CustomFormat Indicates that the value of the CustomFormat property is inherited from the control.

NullText Indicates that the value of the NullText property is inherited from the control.



EmptyAsNull Indicates that the value of the EmptyAsNull property is inherited from the control.

TrimStart Indicates that the value of the TrimStart property is inherited from the control.

TrimEnd Indicates that the value of the TrimEnd property is inherited from the control.

All Indicates that values of CaseSensitive, FormatType, CustomFormat, NullText, EmptyAsNull, TrimStart, and TrimEnd properties are inherited from the control.

PostValidationInheritFlags Enumeration Used by PostValidation.Inherit property.

Syntax

[VB]

Public Enum PostValidationInheritFlags

[C#]

public sealed enum PostValidationInheritFlags : System.Enum

[Delphi]

type PostValidationInheritFlags = (None, CaseSensitive);




PostValidationTypeEnum Enumeration Used by PostValidation.Validation property.

Syntax

[VB]

Public Enum PostValidationTypeEnum

[C#]

public sealed enum PostValidationTypeEnum : System.Enum

[Delphi]

type PostValidationTypeEnum = (ValuesAndIntervals, PostValidatingEvent);

PreValidationInheritFlags Enumeration· 291


ValuesAndIntervals Validation using Values and Intervals.

PostValidatingEvent Using the PostValidating event.

PreValidationInheritFlags Enumeration Used by PreValidation.Inherit property.

Syntax

[VB]

Public Enum PreValidationInheritFlags

[C#]

public sealed enum PreValidationInheritFlags : System.Enum

[Delphi]

type PreValidationInheritFlags = (None, CaseSensitive, TrimStart, TrimEnd, All);




TrimStart Indicates that the value of the TrimStart property is inherited from the control.

TrimEnd Indicates that the value of the TrimEnd property is inherited from the control.

All Indicates that values of CaseSensitive, TrimStart, and TrimEnd properties are inherited from the control.

PreValidationTypeEnum Enumeration Used by PreValidation.Validation property.

Syntax

[VB]

Public Enum PreValidationTypeEnum

[C#]

public sealed enum PreValidationTypeEnum : System.Enum

[Delphi]

type PreValidationTypeEnum = (ExactList, PreValidatingEvent, Wildcards, RegexPattern);


ExactList The PatternString property contains a list of possible values separated by the ItemSeparator.



PreValidatingEvent Using the PreValidating event.

Wildcards The PatternString property contains a list of wildcard patterns separated by the ItemSeparator. The following characters are reserved in a pattern: ? (any single character), # (any single digit), * (zero or more characters), \ (escape). Also, you can define your own custom pattern characters using the CustomPlaceholders property.

RegexPattern The PatternString property contains a regular expression.

RegexOptionFlags Enumeration Used by PreValidation.RegexOptions property.

Syntax

[VB]

Public Enum RegexOptionFlags

[C#]

public sealed enum RegexOptionFlags : System.Enum

[Delphi]

type RegexOptionFlags = (None, ECMAScript, ExplicitCapture, IgnorePatternWhitespace, MultiLine, RightToLeft, SingleLine);


None Specifies that no options are set.

ECMAScript Enables ECMAScript-compliant behavior for the expression. This flag can be used only in conjunction with the IgnoreCase, Multiline, and Compiled flags. The use of this flag with any other flags results in an exception.

ExplicitCapture Specifies that the only valid captures are explicitly named or numbered groups of the form (?<name>…). This allows unnamed parentheses to act as noncapturing groups without the syntactic clumsiness of the expression (?:…).

IgnorePatternWhitespace Eliminates unescaped white space from the pattern and enables comments marked with #.

Multiline Multiline mode. Changes the meaning of ^ and $ so they match at the beginning and end, respectively, of any line, and not just the beginning and end of the entire string.

RightToLeft Specifies that the search will be from right to left instead of from left to right.

Singleline Specifies single-line mode. Changes the meaning of the dot (.) so it matches every character (instead of every character except \n).

ShowLiteralsEnum Enumeration· 293

ShowLiteralsEnum Enumeration Used by MaskInfo.ShowLiterals property.

Syntax

[VB]

Public Enum ShowLiteralsEnum

[C#]

public sealed enum ShowLiteralsEnum : System.Enum

[Delphi]

type ShowLiteralsEnum = (ShowAlways, FreeFormatEntry, WhenNextStarted, WhenPrevFilled);


ShowAlways Whole mask is shown when editing begins (empty space filled with PromptChar).

FreeFormatEntry The mask is validated on exit. No literals or prompt chars are displayed automatically.

WhenNextStarted The literals will be inserted after the user enters the first character of the field that follows the literals.

WhenPrevFilled Literals that follow the input mask will be inserted after the user enters the last character in the current field.

VerticalAlignEnum Enumeration Used by C1TextBox.VerticalAlign property.

Syntax

[VB]

Public Enum VerticalAlignEnum

[C#]

public sealed enum VerticalAlignEnum : System.Enum

[Delphi]

type VerticalAlignEnum = (Top, Middle, Bottom);


Top Text is aligned with the top of the enclosing control.

Middle Text is aligned with the center of the enclosing control.

Bottom Text is aligned with the bottom of the enclosing control.


C1Input Event Handler Reference CultureInfoSetupEventHandler Delegate

Syntax

[VB]

public delegate void CultureInfoSetupEventHandler(object sender, CultureInfoSetupEventArgs e)

[C#]

public sealed delegate CultureInfoSetupEventHandler : MulticastDelegate

[Delphi]

type CultureInfoSetupEventHandler = procedure(sender: System.Object; e: CultureInfoSetupEventArgs) of object;

Arguments

Argument Description

Sender The source of the event

e A CultureInfoSetupEventArgs object that contains the event data

See Also

CultureInfoSetup Event (page 189)

EventHandler Delegate See Microsoft .Net Framework documentation.

See Also

DataTypeChanged Event (page 189)

DropDownOpened Event (page 81)

DropDownClosed Event (page 80)

ValueChanged Event (page 195)

PositionChanged Event (page 127)

RefreshData Event (page 128)

UpdateData Event (page 128)

FormatErrorEventHandler Delegate Syntax

[VB

public delegate void FormatErrorEventHandler(object sender, FormatErrorEventArgs e)

[C#]

public sealed delegate FormatErrorEventHandler : System.MulticastDelegate

FormatEventHandler Delegate· 295

[Delphi]

type FormatErrorEventHandler = procedure(sender: System.Object; e: FormatErrorEventArgs) of object;

Arguments



e A FormatErrorEventArgs object that contains the event data

See Also

FormatError Event (page 190)

FormatEventHandler Delegate Syntax

[VB]

public delegate void FormatEventHandler(object sender, FormatEventArgs e)

[C#]

public sealed delegate FormatEventHandler : System.MulticastDelegate

[Delphi]

type FormatEventHandler = procedure(sender: System.Object; e: FormatEventArgs) of object;

Arguments



e A FormatEventArgs object that contains the event data

See Also

Formatting Event (page 191)

NavigatorBeforeActionEventHandler Delegate Syntax

[VB]

public delegate void NavigatorBeforeActionEventHandler(object sender, NavigatorBeforeActionEventArgs e);

[C#]

public sealed delegate NavigatorBeforeActionEventHandler : System.MulticastDelegate

[Delphi]

type NavigatorBeforeActionEventHandler = procedure(sender: System.Object; e: NavigatorBeforeActionEventArgs) of object;


Arguments



e A NavigatorBeforeActionEventArgs object that contains the event data

See Also

BeforeAction Event (page 125)

NavigatorButtonClickEventHandler Delegate Syntax

[VB]

public delegate void NavigatorButtonClickEventHandler(object sender, NavigatorButtonClickEventArgs e)

[C#]

public sealed delegate NavigatorButtonClickEventHandler : System.MulticastDelegate

[Delphi]

type NavigatorButtonClickEventHandler = procedure(sender: System.Object; e: NavigatorButtonClickEventArgs) of object;

Arguments



e A NavigatorButtonClickEventArgs object that contains the event data

See Also

ButtonClick

NavigatorEditingEventHandler Delegate Syntax

[VB]

public delegate void NavigatorEditingEventHandler(object sender, NavigatorEditingEventArgs e)

[C#]

public sealed delegate NavigatorEditingEventHandler : System.MulticastDelegate

[Delphi]

type NavigatorEditingEventHandler = procedure(sender: System.Object; e: NavigatorEditingEventArgs) of object;

Arguments



e A NavigatorEditingEventArgs object that contains the event data

NavigatorErrorEventHandler Delegate· 297

See Also

Editing Event (page 126)

NavigatorErrorEventHandler Delegate Syntax

[VB]

public delegate void NavigatorErrorEventHandler(object sender, NavigatorErrorEventArgs e)

[C#]

public sealed delegate NavigatorErrorEventHandler : System.MulticastDelegate

[Delphi]

type NavigatorErrorEventHandler = procedure(sender: System.Object; e: NavigatorErrorEventArgs) of object;

Arguments



e A NavigatorEditingEventArgs object that contains the event data

See Also

Error Event (page 126)

NullableDateTimeEventHandler Delegate Syntax

[VB]

public delegate void NullableDateTimeEventHandler(object sender, NullableDateTimeEventArgs e)

[C#]

public sealed delegate NullableDateTimeEventHandler : System.MulticastDelegate

[Delphi]

type NullableDateTimeEventHandler = procedure(sender: System.Object; e: NullableDateTimeEventArgs) of object;

Arguments



e A NullableDateTimeEventArgs object that contains the event data

See Also

DateChanged Event (page 200)

DateSelected Event (page 200)


ParseEventHandler Delegate Syntax

[VB]

public delegate void ParseEventHandler(object sender, ParseEventArgs e)

[C#]

public sealed delegate ParseEventHandler : System.MulticastDelegate

[Delphi]

type ParseEventHandler = procedure(sender: System.Object; e: ParseEventArgs) of object;

Arguments



e A ParseEventArgs object that contains the event data

See Also

Parsing Event (page 192)

Parsed Event (page 192)

PostValidationEventHandler Delegate Syntax

[VB]

public delegate void PostValidationEventHandler(object sender, PostValidationEventArgs e);

[C#]

public sealed delegate PostValidationEventHandler : System.MulticastDelegate

[Delphi]

type PostValidationEventHandler = procedure(sender: System.Object; e: PostValidationEventArgs) of object;

Arguments



e A PostValidationEventArgs object that contains the event data

See Also

PostValidating Event (page 193)

PostValidated Event (page 193)

PreValidationEventHandler Delegate· 299

PreValidationEventHandler Delegate Syntax

[VB]

public delegate void PreValidationEventHandler(object sender, PreValidationEventArgs e);

[C#]

public sealed delegate PreValidationEventHandler : System.MulticastDelegate

[Delphi]

type PreValidationEventHandler = procedure(sender: System.Object; e: PreValidationEventArgs) of object;

Arguments



e A PreValidationEventArgs object that contains the event data

See Also

PreValidating Event (page 194)

PreValidated Event (page 194)

UpDownButtonClickEventHandler Delegate Syntax

[VB]

public delegate void UpDownButtonClickEventHandler(object sender, UpDownButtonClickEventArgs e)

[C#]

public sealed delegate UpDownButtonClickEventHandler : System.MulticastDelegate

[Delphi]

type UpDownButtonClickEventHandler = procedure(sender: System.Object; e: UpDownButtonClickEventArgs) of object;

Arguments



e An UpDownButtonClickEventArgs object that contains the event data

See Also

UpDownButtonClick Event (page 82)


ValidationErrorEventHandler Delegate Syntax

[VB]

public delegate void ValidationErrorEventHandler(object sender, ValidationErrorEventArgs e);

[C#]

public sealed delegate ValidationErrorEventHandler : System.MulticastDelegate

[Delphi]

type ValidationErrorEventHandler = procedure(sender: System.Object; e: ValidationErrorEventArgs) of object;

Arguments



e A ValidationErrorEventArgs object that contains the event data

See Also

ValidationError Event (page 195)

C1Input Event Arguments Reference CultureInfoSetupEventArgs Class

Syntax

[VB]

Public Class CultureInfoSetupEventArgs

[C#]

public class CultureInfoSetupEventArgs : System.EventArgs

[Delphi]

type CultureInfoSetupEventArgs: class(EventArgs);

Members

Member Description

CultureInfo cultureInfo Regional settings. Settings can be changed in event code for all cultures except "(Current Culture)" and "(Invariant Culture)".

See Also

CultureInfoSetupEventHandler Delegate (page 294)

FormatErrorEventArgs Class· 301

FormatErrorEventArgs Class Syntax

[VB]

Public Class FormatErrorEventArgs

[C#]

public class FormatErrorEventArgs : System.EventArgs

[Delphi]

type FormatErrorEventArgs: class(EventArgs);

Members

Member Description

object Value Source value for formatting.

string ErrorMessage Error description shown as the tooltip in the ErrorProvider icon, if ErrorInfo.ErrorProvider property is set (C1Label.ErrorProvider in C1Label control). Your code in FormatError event can change this argument to customize error description.

FormatTargetEnum Target

Formatting target (ForEdit or ForDisplay).

FormatInfo FormatInfo

FormatInfo object that fired the event.

string Text The text to show in the control. Your code in FormatError event can set this argument to a text you want to show in the control in case of a formatting error.

See Also

FormatErrorEventHandler Delegate (page 294)

FormatEventArgs Class Syntax

[VB]

Public Class FormatEventArgs

[C#]

public class FormatEventArgs : System.EventArgs

[Delphi]

type FormatEventArgs: class(EventArgs);

Members

Member Description

object Value Source value for formatting.

string ErrorMessage The out parameter for specifying error description if Succeeded is set to False.


Member Description

FormatTargetEnum Target

Formatting target (ForEdit or ForDisplay).

FormatInfo FormatInfo

FormatInfo object that fired the event.

string Text The out parameter for the resulting string (in Formatting), or the in parameter for the formatted string (in Formatted).

See Also

FormatEventHandler Delegate (page 295)

NavigatorBeforeActionEventArgs Class Syntax

[VB]

Public Class NavigatorBeforeActionEventArgs

[C#]

public class NavigatorBeforeActionEventArgs : System.EventArgs

[Delphi]

type NavigatorBeforeActionEventArgs: class(EventArgs);

Members

Member Description

NavigatorButtonEnum Button The clicked button.

int Index Current row index in the data source (only for Delete and Edit buttons).

bool Cancel This argument is False by default. If you set it to True in your event code, the navigator control will skip the standard action associated with the button.

See Also

NavigatorBeforeActionEventHandler Delegate (page 295)

NavigatorButtonClickEventArgs Class Syntax

[VB]

Public Class NavigatorButtonClickEventArgs

[C#]

public class NavigatorButtonClickEventArgs : System.EventArgs

NavigatorEditingEventArgs Class· 303

[Delphi]

type NavigatorButtonClickEventArgs: class(EventArgs);

Members

Member Description

NavigatorButtonEnum Button

The clicked button.

See Also

NavigatorButtonClickEventHandler Delegate (page 296)

NavigatorEditingEventArgs Class Syntax

[VB]

Public Class NavigatorEditingEventArgs

[C#]

public class NavigatorEditingEventArgs : System.EventArgs

[Delphi]

type NavigatorEditingEventArgs: class(EventArgs);

Members

Member Description

int Index The index of the row being edited.

See Also

NavigatorEditingEventHandler Delegate (page 296)

NavigatorErrorEventArgs Class Syntax

[VB]

Public Class NavigatorErrorEventArgs

[C#]

public class NavigatorErrorEventArgs : System.EventArgs

[Delphi]

type NavigatorErrorEventArgs: class(EventArgs);

Members

Member Description

NavigatorButtonEnum Button The clicked C1DbNavigator button.

Exception Exception Exception that occurred while performing the button action.


Member Description

bool ShowErrorMessage This argument is set to true by default. If it is set to False by event code, the standard message box is not shown.

string ErrorMessage Error message shown in the standard message box. The programmer can set this argument to change the message.

string ErrorMessageCaption The caption of the standard message box. The programmer can set this argument to change the caption.

See Also

NavigatorErrorEventHandler Delegate (page 297)

NullableDateTimeEventArgs Class Syntax

[VB]

Public Class NullableDateTimeEventArgs

[C#]

public class NullableDateTimeEventArgs : System.EventArgs

[Delphi]

type NullableDateTimeEventArgs: class(EventArgs);

Members

Member Description

DateTime Date The date value.

bool DateIsNull Set to True if the date value is null.

See Also

NullableDateTimeEventHandler Delegate (page 297)

ParseEventArgs Class Syntax

[VB]

Public Class ParseEventArgs

[C#]

public class ParseEventArgs : System.EventArgs

[Delphi]

type ParseEventArgs: class(EventArgs);

PostValidationEventArgs Class· 305

Members

Member Description

string Text Source string for parsing

Type DestinationType Data type to convert the string to.

ParseInfo ParseInfo ParseInfo object that fired the event.

object Value Property to save the result to (in Parsing) or to get the resulting value from (in Parsed).

ErrorInfo ErrorInfo Error information in case of parsing failure. Can be set in event code in Parsing.

See Also

ParseEventHandler Delegate (page 297)

PostValidationEventArgs Class Syntax

[VB]

Public Class PostValidationEventArgs

[C#]

public class PostValidationEventArgs : System.EventArgs

[Delphi]

type PostValidationEventArgs: class(EventArgs);

Members

Member Description

object Value The value to validate.

PostValidation PostValidation

PostValidation object that fired the event.

ErrorInfo ErrorInfo Error information in case of validation failure. Can be set in event code in PostValidating.

bool Succeeded Validation result (assigned in the event code in PostValidating). Default: True

See Also

PostValidationEventHandler Delegate (page 298)


PreValidationEventArgs Class Syntax

[VB]

Public Class PreValidationEventArgs

[C#]

public class PreValidationEventArgs : System.EventArgs

[Delphi]

type PreValidationEventArgs: class(EventArgs);

Members

Member Description

string Text The text to validate.

PreValidation PreValidation

PreValidation object that fired the event.

ErrorInfo ErrorInfo Error information in case of validation failure. Can be set in event code in PreValidating.

bool Succeeded Validation result (assigned in the event code in PreValidating). Default: True.

See Also

PreValidationEventHandler Delegate (page 298)

UpDownButtonClickEventArgs Class Syntax

[VB]

Public Class UpDownButtonClickEventArgs

[C#]

public class UpDownButtonClickEventArgs : System.EventArgs

[Delphi]

type UpDownButtonClickEventArgs: class(EventArgs);

Members

Member Description

int Delta Set to 1 if Up button is pressed, to -1 if Down button is pressed.

See Also

UpDownButtonClickEventHandler Delegate (page 299)

ValidationErrorEventArgs Class· 307

ValidationErrorEventArgs Class Syntax

[VB]

Public Class ValidationErrorEventArgs

[C#]

public class ValidationErrorEventArgs : System.EventArgs

[Delphi]

type ValidationErrorEventArgs: class(EventArgs);

Members

Member Description

string Text The input text that caused the error.

object Value If Reason = ErrorReasonEnum.PostValidationError, this is the value that caused the error. Otherwise, this property is null or DBNull.

ErrorReasonEnum Reason

Validation phase on which the error has been detected.

ErrorInfo ErrorInfo Error information.

C1Input Exception Reference DataSourceException Exception

An exception thrown by C1Input when a control's Value property is set, but the new value is rejected by the data source, setting the data field to that value is cancelled by the data source throwing an exception.

System.Object System.Exception System.ApplicationException C1.Win.C1Input.DataSourceException

InnerException Property (DataSourceException) Exception thrown by the data source on the attempt to set data field value.

Syntax

[VB]

Public ReadOnly Property InnerException As Exception

[C#]

public Exception InnerException {get;}

[Delphi]

property InnerException: Exception;


Remarks

This property is inherited from the Exception class.

See Also

DataSourceException Exception (page 307)

Sender Property Control that caused the exception.

Syntax

[VB]

Public ReadOnly Property Sender As Object

[C#]

public object Sender {get;}

[Delphi]

property Sender: Object;

See Also


Value Property (DataSourceException) Current value in the control that caused the exception.

Syntax

[VB]

Public ReadOnly Property Value As Object

[C#]

public object Value {get;}

[Delphi]


See Also


ValidationException Exception An exception that follows the ValidationError event if ValidationErrorEventArgs.ErrorInfo is set to ErrorActionEnum.ThrowException.

System.Object System.Exception System.ApplicationException C1.Win.C1Input.ValidationException

Reason Property (ValidationException)· 309

Reason Property (ValidationException) Validation phase on which the error has been detected.

Syntax

[VB]

Public Property Reason As ErrorReasonEnum

[C#]

public ErrorReasonEnum Reason {get;}

[Delphi]

property Reason: ErrorReasonEnum;

See Also

ValidationException Exception (page 308)

Sender Property (ValidationException) Control that fired the exception.

Syntax

[VB]

Public Property Sender As Object

[C#]

public object Sender {get;}

[Delphi]

property Sender: Object;

See Also


Text Property (ValidationException) The input text that caused the error.

Syntax

[VB]

Public Property Text As String

[C#]

public string Text {get;}

[Delphi]

property Text: string;

See Also



Value Property (ValidationException) The typed value that caused the error.

Syntax

[VB]

Public Property Value As Object

[C#]

public object Value {get;}

[Delphi]


Remarks

If Reason:ValidationException = ErrorReasonEnum.PostValidationError, this is the value that caused the error. Otherwise, this property is null or DBNull.

See Also

ValidationException Exception

Index · 311

IndexA AcceptsEscape property 156 Add method 260, 269

of PlaceholderCollection 260 of ValueIntervalCollection 269

AddRange method 269 of ValueIntervalCollection 269

AllowDbNull property 157, 247 of PostValidation 247

AutoChangePosition property 158 AutoTabWhenFilled property 226

B BeepOnError property 273 BeforeAction event 125 BindingFormatting event 188 BindingParsing event 188 BorderStyle property 111, 256

of C1DbNavigator 111 of DropDownForm 256

Bottom property 221 ButtonClick event 126 ButtonCursor property 111 ButtonCursorChanged event 125 ButtonFlatStyle property 202 ButtonSize property 112 ButtonStyle property 112 ButtonTextAlign property 113 ButtonTexts property 113 ButtonToolTips property 113

C Calculator property 103 Calendar property 92 CancelChanges event 258 CanLoseFocus property 273 CaseSensitive property 158, 211, 226, 239, 247, 253

of CustomPlaceholder 253 of MaskInfo 226 of ParseInfo 211 of PostValidation 247 of PreValidation 239

CausesFormValidation property 114 CausesValidation property 159

Changed event 224 CheckValidationResult method 183 ClearButtonClick event 199 ClearButtonVisibilityChanged event 200 ClickButton method 123 CloseDropDown method 79 ColorButtons property 114 ColorWhenHover property 115 ConfirmDelete property 115 Contains method 261, 270


Content property 227 CopyImage method 143 CopyTo method 261, 270


CopyWithLiterals property 159, 227 of C1TextBox 159 of MaskInfo 227

Culture property 160 CultureInfo property 160 CultureInfoSetup event 189 CultureInfoSetupEventArgs class 300 CultureInfoSetupEventHandler delegate 294 CultureName property 161 CurrencyManager property 115 CurrentTimeZone property 161 CustomFormat property 162, 205, 211

of FormatInfo 205 of ParseInfo 211

CustomPlaceholder constructor 252 CustomPlaceholders property 228, 239

of MaskInfo 228 of PreValidation 239

D DataField property 163 DataMember property 116 DataSource property 116, 163

of C1DbNavigator 116 DataType property 164, 265

of ValueInterval 265 DataTypeChanged event 190 Date property 198 DateChanged event 200 DateIsNull property 198

312 · Index

DateSelected event 201 DateTimeInput property 166 DateTimeStyle property 212 DateTimeStyleFlags enumeration 278 DaylightTimeAdjustment property 165 DaylightTimeAdjustmentEnum enumeration 279 DecDateTimeInput method 183 DefaultDropDownFormClassName property 74 DisableOnNoData property 165 DisplayFormat property 166, 203 DropDownAlign property 256 DropDownClosed event 80 DropDownControlButtonFlags enumeration 279 DropDownForm property 75 DropDownFormAlign property 75 DropDownFormAlignChanged event 80 DropDownFormAlignmentEnum enumeration 280 DropDownFormClassName property 76 DropDownFormOptionsFlags enumeration 280 DropDownOpened event 81 DroppedDown property 76

E EditablePositionCount property 228 EditFormat property 167 Editing event 126 EditMask property 167, 229

of MaskInfo 229 EditMode property 168 EffectiveText property 229 EmptyAsNull property 168, 206, 212, 229

of FormatInfo 206 of MaskInfo 229 of ParseInfo 212

EnabledButtons property 117 Error event 126 ErrorAction property 274 ErrorActionEnum enumeration 281 ErrorInfo property 169 ErrorMessage property 213, 230, 240, 248, 274

of MaskInfo 230 of ParseInfo 213 of PostValidation 248 of PreValidation 240

ErrorMessageCaption property 275 ErrorProvider property 117, 136, 275

of C1DbNavigator 117 of C1Label 136 of ErrorInfo 275

ErrorReasonEnum enumeration 281 EventHandler delegate 294 Excluding property 253

F FocusControl property 256 ForeColor property 117 Format method 209 FormatError event 190 FormatErrorEventArgs class 301 FormatErrorEventHandler delegate 294 FormatEventArgs class 301 FormatEventHandler delegate 295 FormatInfo property 136 FormatInfoInheritFlags enumeration 282 FormatOnClose property 203 FormatTargetEnum enumeration 283 Formatted event 191 Formatting event 191 FormatType property 169, 206, 213


FormatTypeEnum enumeration 283

G GapHeight property 76 GetContent method 235 GetDisplayText method 235 GetItem method 263

of PlaceholderCollection 263 GetStoredText method 236 GMTOffset property 170

H HorizontalIndent property 118

I ImageChanged event 145 ImageFromByteArray method 144 ImageList property 118 ImageListHighlight property 119 ImageToByteArray method 144 ImmediateUpdate property 143 IncDateTimeInput method 184 IncludeMax property 265 IncludeMin property 265 Increment property 103 IndexOf method 262, 271


Inherit property 207, 214, 230, 240, 248 of FormatInfo 207 of MaskInfo 230 of ParseInfo 214 of PostValidation 248 of PreValidation 240

Index · 313

InitialSelection property 170 InitialSelectionEnum enumeration 283 InnerException property 276, 307

of DataSourceException 307 of ErrorInfo 276

Insert method 262, 271 of PlaceholderCollection 262 of ValueIntervalCollection 271

InterceptArrowKeys property 77 Intervals property 249 IsMaskedMode method 236 IsTextDbNull method 216 IsValid method 237 Item property 268, 277

of UIStrings 277 of ValueIntervalCollection 268

ItemChanged event 127 ItemSeparator property 241

L Label property 171 Left property 222 Lines property 171 LookupChars property 254

M Margins constructor 221 Margins property 172 MarginsChanged event 192 MaskInfo property 172 MaskInfoInheritFlags enumeration 284 MatchExactList method 243 MatchRegex method 244 MatchWildcardPattern method 244 MatchWildcardPatterns method 245 MaxValue property 266 MinShortYear property 173 MinValue property 266 ModalButtonClick event 81 Modified property 173 MouseClickPassThrough property 77 MoveDelayFirst property 119 MoveDelayNext property 120

N NavigatorBeforeActionEventArgs class 302 NavigatorBeforeActionEventHandler delegate 295 NavigatorButtonClickEventArgs class 302 NavigatorButtonClickEventHandler delegate 296 NavigatorButtonEnum enumeration 284 NavigatorButtonFlags enumeration 285 NavigatorButtonStyleEnum enumeration 286 NavigatorButtonTextAlignEnum enumeration 286

NavigatorEditingEventArgs class 303 NavigatorEditingEventHandler delegate 296 NavigatorErrorEventArgs class 303 NavigatorErrorEventHandler delegate 297 NavigatorVerticalAlignEnum enumeration 288 NullableDateTimeEventArgs class 304 NullableDateTimeEventHandler delegate 297 NullText property 174, 207, 214


NumberStyle property 214 NumberStyleFlags enumeration 287 NumericInput property 174 NumericInputKeyFlags enumeration 288 NumericInputKeys property 175

O Open event 258 OpenDropDown method 80 Optional property 254 Options property 257 OwnerControl property 257 OwnerControlTextChanged event 258 OwnerControlValueChanged event 259

P PageSize property 120 Parse method 216 ParseBoolean method 217 ParseContent method 184 Parsed event 192 ParseDateTime method 218 ParseEventArgs class 304 ParseEventHandler delegate 298 ParseFixed method 218 ParseFloat method 219 ParseInfo property 175 ParseInfoInheritFlags enumeration 289 ParseInteger method 220 Parsing event 193 PasteImage method 145 PatternString property 241 Placeholder property 254 Position property 120 PositionChanged event 127 PositionVisible property 121 PostChanges event 259 PostValidated event 193 PostValidating event 194 PostValidation property 176 PostValidationEventArgs class 305 PostValidationEventHandler delegate 298 PostValidationInheritFlags enumeration 290 PostValidationTypeEnum enumeration 290

314 · Index

PreValidated event 194 PreValidating event 195 PreValidation property 176 PreValidationEventArgs class 306 PreValidationEventHandler delegate 299 PreValidationInheritFlags enumeration 291 PreValidationTypeEnum enumeration 291 PromptChar property 231

R Reason property 309

of ValidationException 309 RefreshData event 128 RegexOptionFlags enumeration 292 RegexOptions property 242 Remove method 263, 272


Reset method 223 ResetContent method 237 ResetText method 185 Right property 222 RowCount property 121

S SaveBlanks property 231 SaveLiterals property 232 Sender property 308, 309

of ValidationException 309 Set method 223 SetDataBinding method 124 SetProposedValue method 186 ShouldSerialize method 224 ShowClearButton property 199 ShowContextMenu property 177 ShowDropDownButton property 78 ShowErrorMessage property 276 ShowFocusRectangle property 177 ShowLiterals property 232 ShowLiteralsEnum enumeration 293 ShowModalButton property 78 ShowTodayButton property 198 ShowToolTips property 121 ShowUpDownButtons property 78 SkipOptional property 233 StoredContent property 234 StoredEmptyChar property 234 StoredFormat property 203 SuspendNumericInput method 186

T Text property 178, 309

of ValidationException 309

TextDetached property 178 TodayButtonClick event 201 TodayButtonVisibilityChanged event 201 Top property 222 TrimEnd property 179, 208, 215, 242

of FormatInfo 208 of ParseInfo 215 of PreValidation 242

TrimStart property 179, 208, 215, 242 of FormatInfo 208 of ParseInfo 215 of PreValidation 242

U UIStrings property 122, 199, 204

of C1DbNavigator 122 of DateEditMonthCalendar 199 of NumericEditCalculator 204

UpdateData event 128 UpdateValueWithCurrentText method 187 UpDownButtonClick event 82 UpDownButtonClickEventArgs class 306 UpDownButtonClickEventHandler delegate 299 UseMaxValue property 266 UseMinValue property 267 UserCultureOverride property 180 UseStaticMemory property 204

V Validate method 245, 250

of PostValidation 250 of PreValidation 245

ValidateValuesAndIntervals method 251 Validation property 243, 249

of PostValidation 249 of PreValidation 243

ValidationError event 195 ValidationErrorEventArgs class 307 ValidationErrorEventHandler delegate 300 Value property 181, 308, 310

of DataSourceException 308 of ValidationException 310

ValueChanged event 196 ValueInterval constructor 264 ValueIntervalCollection constructor 268 ValueIsDbNull property 181 ValueOnError property 276 ValueOnErrorIsDbNull property 277 Values property 249 ValuesExcluded property 250 VerticalAlign property 122, 182 VerticalAlignChanged event 196 VerticalAlignEnum enumeration 293 VerticalIndent property 123

Index · 315

VisibleButtons property 79, 123 of C1DbNavigator 123

W WrapDateTimeFields property 182