Input for Winforms

ComponentOne Input for WinForms ComponentOne, a division of GrapeCity 201 South Highland Avenue, Third Floor Pittsburgh, PA 15206 USA Website: http://www.componentone.com Sales: [email protected] Telephone: 1.800.858.2739 or 1.412.681.4343 (Pittsburgh, PA USA Office)

Trademarks

The ComponentOne product name is a trademark and ComponentOne is a registered trademark of GrapeCity, Inc. All other trademarks used herein are the properties of their respective owners.

Warranty

ComponentOne warrants that the media on which the software is delivered is 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 media 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 the defective media by sending it and a check for $2 5 (to cover postage and handling) to ComponentOne. Except for the express warranty of the original media on which the software is delivered is 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. ComponentOne is 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. Input for WinForms 1

Table of Contents

Input for WinForms Overview 5 Differences from the .NET 1.x Version 5 Help with WinForms Edition 5 Key Features 6 Design-Time Support 7 C1Button Tasks Menu 7 C1CheckBox Tasks Menu 7-8 C1ComboBox Context Menu 8 C1ComboBox Tasks Menu 8-9 C1DateEdit Tasks Menu 9 C1DbNavigator Tasks Menu 9-10 C1DropDownControl Tasks Menu 10 C1Label Tasks Menu 10-11 C1NumericEdit Tasks Menu 11 C1RangeSliderTasks Menu 11-12 C1SplitButton Context Menu 12-13 C1SplitButton Tasks Menu 13 C1TextBox Tasks Menu 13-14 C1ColorPicker Tasks Menu 14 C1FontPicker Tasks Menu 14-15 Using the C1Input Controls 16 C1Input Controls 16-17 C1DbNavigator Control Overview 17-18 C1DbNavigator Appearance 18-19 C1DbNavigator Behavior 19-20 C1ComboBox Control Overview 20 C1ComboBox Elements 20-21 ComboBox Item Modes 21-23 C1ComboBox Styling 23 C1ComboBox Button Appearance 23-24 ComboBox DataBinding 24 Adding Images to Items in the ComboBox 24-25 Adding Items to C1ComboBox 25-26 Removing Items from C1ComboBox 26-27

Populating C1ComboBox with Data Using SelectedItemChanged Event 27-29 Populating C1Combbox with Data Using the SelectedIndexChanged Event 29-30 C1RangeSlider Control Overview 30 C1RangeSlider Elements 30-31 C1RangeSlider Features 31 Maximum and Minimum Values 31 Orientation 31-32 Thumb Values and Range 32 C1RangeSlider Appearance 32 Background Image 32-33 Bar Style 33-37 Thumb Style 37-42 C1ColorPicker Control Overview 42 C1ColorPicker Elements 42-44 Working with C1ColorPicker 44-45 Applying Visual Styles to C1ColorPicker 45-46 C1FontPicker Control Overview 46 C1FontPicker Elements 46-47 Working with C1FontPicker 47-48 Applying Visual Styles to C1Font Picker 48-49 Data Binding 49-50 Value and Text: Displaying, Validating, and Updating Values 50-51 Formatting Data 51 Format Types 51-53 Custom Format Specifiers 53 Numeric Custom Format Specifiers 53-56 Date-Time Custom Format Specifiers 56-61 Parsing (Updating) Data 61 Culture (Regional) Settings 61-62 Edit Mask 62-64 Validating Data 64 Input String Validation (PreValidation) 64-65 Typed Value Validation (PostValidation) 65 Editing Date and Time Values 65-66 Editing Numeric Values 66 Drop-Down and Increment Buttons 66

C1DateEdit Control 66-67 C1NumericEdit Control 67 Custom Drop-Down 67 Programmatic Formatting, Parsing, and Validation 67-68 Error Handling 68 Data Errors 68 Incorrect Format in Displaying Data 68 User Input Errors 68-70 Handling NULL and Empty Values 70 Displaying NULL and Empty Values 70 Entering NULL and Empty Values 70 Customizing C1Input's Appearance 71 Visual Styles 71-81 Themes 81-87 C1Themes and the VisualStyle Property 87 Border Styles 87-88 Cursor Styles 88-90 Flat Styles 90-91 Button Color 91 Input for WinForms Task-Based Help 92 Adding a Drop-Down Form 92-94 Changing the Navigation in the Navigator 94-95 Customizing the Drop-Down Editor 95-97 Customizing the C1DropDownControl 97 Binding C1CheckBox 97 Binding C1CheckBox to a Boolean Field 97-98 Binding C1CheckBox to a String Field 98 Binding C1CheckBox to an Integer Field 98-99 Setting the Calendar Drop-down 99-101 Customizing Appearance Using Visual Styles 101-102 Customizing the C1DateEdit Control 102-103 Displaying Clicked C1DropDown Buttons in a Text Box 103-104 Working with a Database 104 Creating a New Connection 104-106 Updating /Refreshing Data from the Database 106-107 Creating a Master-Detail Relation 107-108

Customizing the PictureBox 108-112 Navigating the C1DateEdit Control 112-115 Displaying a Border Color for the C1Input Controls 115-116 Showing a Message Box when the Border Color Changes 116-117 Set IME Mode 117-118 Move Focus 118-119 Select Specific Calendar Type 119 Spin Up/Spin Down Programmatically 119-120 Change Up-Down Button Alignment 120 Input for WinForms Samples 121-122 Input for WinForms Tutorials 123 Binding C1Input Controls to a Data Source 123 Binding to a C1DataExpress Data Source 123-125 Binding to an ADO.NET Data Source 125-130 Masked Input 130-137 Masked Input Using Regular Expressions 137-139 Data Navigation and Actions Using C1DbNavigator 139-142 Using C1TextBox for Date-Time Input 142-146 Data Validation 146-151 Data Formatting and Parsing 151-157 Using C1DateEdit and C1NumericEdit Controls 157-161 Custom Drop-Down Form 161-165 Editing Numbers in NumericInput Mode 166-169

Input for WinForms Overview

Enhancing the functionality and appearance of the standard controls, Input for WinForms (.NET Framework 2.0) consists of a suite of twelve controls that support Getting Started visual styles (including Office 2010) and data binding. The powerful masked editing capability, rich formatting model, and localization enables you to use these input C1Input Controls controls in your applications with increased performance. Display dynamic data in a Input for WinForms visual format, manage dataset navigation, display or edit dates, and much more. Tutorials Input for WinForms Task-Based Help

Differences from the .NET 1.x Version

Please note that some changes in this version are not compatible with the 1.x versions and may require (minimal) changes to the source code. Changes from the .NET 1.x version include the following:

C1Input 2.x does not reference or need the C1Common assembly. Flag properties, such as FormatInfo, MaskInfo, PreValidatation, and PostValidation, do not show the Inherit flags at design time since those flags are set automatically. Most complex properties can now be reset to the default value in the designer. The CopyWithLiterals property was removed from C1TextBox as it is duplicated in MaskInfo. The AllowDbNull property was removed from C1TextBox and is only available as a sub-property of the PostValidation property. C1DropDownControl now allows the option to specify custom images for its buttons via the new ButtonImages Properties.

Help with WinForms Edition

Getting Started

For information on installing ComponentOne Studio WinForms Edition, licensing, technical support, namespaces and creating a project with the control, please visit Getting Started with WinForms Edition.

Key Features

Display dynamic data in a visual format, manage dataset navigation, display or edit dates, and much more Benefit from using Input for WinForms, featuring:

Support for Office 2007 and 2010 visual styles All C1Input controls support visual styles, including Office 2007 style. Provide attractive and consistent look and feel to your application, especially when used with other ComponentOne controls supporting visual styles. The ability to display dynamic data C1Input controls function in unbound and bound mode. In bound mode, a control’s value is bound to a data source field. Extensive data-binding support Supports data binding to all .NET data sources, including ADO.NET data source objects and DataObjects components. Powerful and customizable masked editing capabilities C1TextBox and all derived controls support powerful masked editing including date and time formats, numeric range, and custom format support. Support for regular expressions in mask format Regular expressions in mask format make validation of complex input data easy. The regular expressions define the pattern of data by using keywords such as \A, {}, and so on. They also provide keywords to validate Japanese characters. The power to format data in almost any way imaginable A rich formatting model enables developers to customize the appearance of a control’s text, border, color, and so on. Support for data validation Supports data validation both of the raw input string (PreValidation) and of the typed value entered by the user (PostValidation). Support for a wide range of cultures Define the cultural setting used by the control – this applies to string comparison, numeric and date time formats, and special characters. Specialized drop-down editors C1DropDownControl allows you to attach your own logic to the spin buttons and your own drop-down form/editor to the drop-down button. Promp input error detection Completely customizable error-handling behavior – detect an error while parsing or validating input value, and respond by showing an error message. Drop-down and increment buttons The specialized C1Input controls for date-time and numeric editing, C1DateEdit, C1NumericEdit, and C1ComboBox controls support drop-down and increment/decrement (up/down) buttons. Slidable Thumbs C1RangeSlider control provides movable thumbs which slide on a bar, enabling you to add numeric data selection to your applications. Various formatting modes to choose from Different formats available - display mode (used for a read-only or non-editing mode control) and edit mode. Ability to quickly resolve NULL and empty values Provides flexible rules for handling NULL and empty values, allowing the programmer to resolve this problem in practically any circumstance. Customizable Appearance Appearance of C1Input controls can be customized, owing to diverse properties and powerful theming capabilities. These provide flexible mechanism for adjusting look of the controls. The C1Input Control also provides two independent controls, C1ColorPicker and C1FontPicker. The C1ColorPicker control provides a rich, interactive color selection interface to select color for your control and C1FontPicker control provides functionality to choose fonts for a text.

Design-Time Support

C1Input provides visual editing to make it easier to configure the C1Input controls. This section describes how to use C1Input's design-time environment to configure the C1Input controls.

Context Menu

You can use the C1Input control's context menu for additional resources at design time.

Tasks Menu

In Visual Studio 2005 2008, and 2010 the C1Input controls include a smart tag. A smart tag represents a short-cut tasks menu that provides the most commonly used properties in each control. You can invoke each control's Tasks menu by clicking on the smart tag ( ) in the upper-right corner of the control. For more information on how to use the smart tags for each control in C1Input, see the following topics.

C1Button Tasks Menu

In the C1Button Tasks menu you can quickly and easily set the VisualStyle property for the C1Button control. To access the C1Button Tasks menu, click on the smart tag ( ) in the upper-right corner of the control. This will open the C1Button Tasks menu.

The C1Button Tasks menu operates as follows:

VisualStyle

Clicking the drop-down arrow in the VisualStyle drop-down opens a list of different VisualStyle enumeration options, such as System, Office2007Blue, Office2007Black, Office2007Silver, Custom, Office2010Blue, Office2010Black, and, Office2010Silver.The default value is Custom. For more information on how to set the VisualStyle property, see Customizing Appearance Using Visual Styles.

About Input

Clicking the About ComponentOne Input link displays the About ComponentOne Input dialog box, which is helpful in finding the version number of the control and online resources.

C1CheckBox Tasks Menu

In the C1CheckBox Tasks menu you can quickly and easily set the VisualStyle property for the C1DateEdit control. To access the C1CheckBox Tasks menu, click on the smart tag ( ) in the upper-right corner of the control. This will open the C1CheckBox Tasks menu.

The C1CheckBox Tasks menu operates as follows:

VisualStyle

Clicking the drop-down arrow in the VisualStyle drop-down opens a list of different VisualStyle enumeration options, such as System, Office2007Blue, Office2007Black, Office2007Silver, Custom, Office2010Blue, Office2010Black, and Office2010Silver. The default value is Custom. For more information on how to set the VisualStyle property, see Customizing Appearance Using Visual Styles.

About Input

Clicking the About ComponentOne Input link displays the About ComponentOne C1Input dialog box, which is helpful in finding the version number of the control and online resources.

C1ComboBox Context Menu

The C1ComboBox control provides a context menu for additional resources at design time. Right-click on the C1ComboBox control to open its context menu.

The C1Input context menu operates as follows: About ComponentOne Input Clicking the About ComponentOne Input link displays the About ComponentOne Input dialog box, which is helpful in finding the version number of the control and online resources. Edit Items... Clicking the Edit Items... opens the String Collection Editor where you enter strings in the collection one per line.

C1ComboBox Tasks Menu

In the C1ComboBox Tasks menu you can quickly and easily set the VisualStyle property for the C1ComboBox control. To access the C1ComboBox Tasks menu, click on the smart tag ( ) in the upper-right corner of the control. This will open the C1ComboBox Tasks menu.

The C1ComboBox Tasks menu operates as follows:

VisualStyle

Clicking the drop-down arrow in the VisualStyle drop-down opens a list of different VisualStyle enumeration options, such as System, Office2007Blue, Office2007Black, Office2007Silver, Custom, Office2010Blue, Office2010Black, and Office2010Silver. The default value is Custom. For more information on how to set the VisualStyle property, see Customizing Appearance Using Visual Styles.

About ComponentOne Input

Clicking the About ComponentOne Input link displays the About ComponentOne C1Input dialog box, which is helpful in finding the version number of the control and online resources.

C1DateEdit Tasks Menu

In the C1DateEdit Tasks menu you can quickly and easily set the VisualStyle property for the C1DateEdit control. To access the C1DateEdit Tasks menu, click on the smart tag ( ) in the upper-right corner of the control. This will open the C1DateEdit Tasks menu.

The C1DataEdit Tasks menu operates as follows:

VisualStyle

Clicking the drop-down arrow in the VisualStyle drop-down opens a list of different VisualStyle enumeration options, such as System, Office2007Blue, Office2007Black, Office2007Silver, Custom, Office2010Blue, Office2010Black, and Office2010Silver. The default value is Custom. For more information on how to set the VisualStyle property, see Customizing Appearance Using Visual Styles.

About ComponentOne Input

Clicking the About ComponentOne Input link displays the About ComponentOne Input dialog box, which is helpful in finding the version number of the control and online resources.

C1DbNavigator Tasks Menu

In the C1DbNavigator Tasks menu you can quickly and easily set the VisualStyle property for the C1DbNavigator control.

To access the C1DbNavigator Tasks menu, click on the smart tag ( ) in the upper-right corner of the control. This will open the C1DbNavigator Tasks menu.

The C1DbNavigator Tasks menu operates as follows:

VisualStyle

Clicking the drop-down arrow in the VisualStyle drop-down opens a list of different VisualStyle enumeration options, such as System, Office2007Blue, Office2007Black, Office2007Silver, and Custom, Office2010Blue, Office2010Black, and Office2010Silver. The default value is Custom. For more information on how to set the VisualStyle property, see Customizing Appearance Using Visual Styles.

About ComponentOne Input

Clicking the About ComponentOne Input link displays the About ComponentOne Input dialog box, which is helpful in finding the version number of the control and online resources.

C1DropDownControl Tasks Menu

In the C1DropDownControl Tasks menu you can quickly and easily set the VisualStyle property for the C1DropDownControl control. To access the C1DropDownControl Tasks menu, click on the smart tag ( ) in the upper-right corner of the control. This will open the C1DropDownControl Tasks menu.

The C1DropDownControl Tasks menu operates as follows:

VisualStyle

Clicking the drop-down arrow in the VisualStyle drop-down opens a list of different VisualStyle enumeration options, such as System, Office2007Blue, Office2007Black, Office2007Silver, Custom, Office2010Blue, Office2010Black, and Office2010Silver. The default value is Custom. For more information on how to set the VisualStyle property, see Customizing Appearance Using Visual Styles.

About ComponentOne Input

Clicking the About ComponentOne Input link displays the About ComponentOne Input dialog box, which is helpful in finding the version number of the control and online resources.

C1Label Tasks Menu

In the C1Label Tasks menu you can quickly and easily set the VisualStyle property for the C1Label control.

To access the C1Label Tasks menu, click on the smart tag ( ) in the upper-right corner of the control. This will open the C1Label Tasks menu.

The C1Label Tasks menu operates as follows:

VisualStyle

Clicking the drop-down arrow in the VisualStyle drop-down opens a list of different VisualStyle enumeration options, such as System, Office2007Blue, Office2007Black, Office2007Silver, Custom, Office2010Blue, Office2010Black, and Office2010Silver. The default value is Custom. For more information on how to set the VisualStyle property, see Customizing Appearance Using Visual Styles.

About ComponentOne Input

Clicking the About ComponentOne Input link displays the About ComponentOne Input dialog box, which is helpful in finding the version number of the control and online resources.

C1NumericEdit Tasks Menu

In the C1NumericEdit Tasks menu you can quickly and easily set the VisualStyle property for the C1NumericEdit control. To access the C1NumericEdit Tasks menu, click on the smart tag ( ) in the upper-right corner of the control. This will open the C1NumericEdit Tasks menu.

The C1NumericEdit Tasks menu operates as follows:

VisualStyle

Clicking the drop-down arrow in the VisualStyle drop-down opens a list of different VisualStyle enumeration options, such as System, Office2007Blue, Office2007Black, Office2007Silver, Custom, Office2010Blue, Office2010Black, and Office2010Silver The default value is Custom. For more information on how to set the VisualStyle property, see Customizing Appearance Using Visual Styles.

About ComponentOne Input

Clicking the About ComponentOne Input link displays the About ComponentOne Input dialog box, which is helpful in finding the version number of the control and online resources.

C1RangeSliderTasks Menu

In the C1RangeSlider Tasks menu you can quickly and easily set the VisualStyle property for

the C1RangeSlider Control. To access the C1RangeSlider Tasks menu, click on the smart tag ( ) in the upper-right corner of the control. This will open the C1RangeSlider Tasks menu.

The C1RangeSlider Tasks menu operates as follows:

VisualStyle

Clicking the drop-down arrow in the VisualStyle drop-down opens a list of different VisualStyle enumeration options, such as System, Office2007Blue, Office2007Black, Office2007Silver, Custom, Office2010Blue, Office2010Black, and Office2010Silver. The default value is Custom. For more information on how to set the VisualStyle property, see Customizing Appearance Using Visual Styles.

About C1.Win.C1 Input

Clicking the About C1.Win.C1Input link displays the About ComponentOne Input dialog box, which is helpful in finding the version number of the control and online resources.

C1SplitButton Context Menu

The C1SplitButton control provides a context menu for additional resources at design time. Right-click on the C1SplitButton control to open its context menu.

Edit Items... Clicking the Edit Items... opens the DropDownItem Collection Editor where you can add or remove dropdown items.

C1SplitButton Tasks Menu

In the C1SplitButton Tasks menu you can quickly and easily set the VisualStyle property for the C1SplitButton control. To access the C1SplittButton Tasks menu, click on the smart tag ( ) in the upper-right corner of the control. This will open the C1SplitButton Tasks menu.

The C1SplitButton Tasks menu operates as follows:

VisualStyle

About ComponentOne Input

Clicking the About ComponentOne Input link displays the About ComponentOne Input dialog box, which is helpful in finding the version number of the control and online resources.

C1TextBox Tasks Menu

In the C1TextBox Tasks menu you can quickly and easily set the VisualStyle property for the C1TextBox control. To access the C1TextBox Tasks menu, click on the smart tag ( ) in the upper-right corner of the control. This will open the C1TextBox Tasks menu.

The C1TextBox Tasks menu operates as follows:

VisualStyle

Clicking the drop-down arrow in the VisualStyle drop-down opens a list of different VisualStyle enumeration options, such as System, Office2007Blue, Office2007Black, Office2007Silver, Custom, Office2010Blue, Office2010Black, and Office2010Silver .The default value is Custom. For more information on how to set the VisualStyle property, see Customizing Appearance Using Visual Styles.

About ComponentOne Input

Clicking the About ComponentOne Input link displays the About ComponentOne Input dialog box, which is helpful in finding the version number of the control and online resources.

C1ColorPicker Tasks Menu

In the C1ColorPicker Tasks menu, you can quickly and easily set the VisualStyle property for the C1ColorPicker control. To access the C1ColorPicker Tasks menu, click on the smart tag ( ) in the upper-right corner of the control. This will open the C1ColorPicker Tasks menu.

The C1ColorPicker Tasks menu operates as follows:

VisualStyle

Clicking the drop-down arrow in the VisualStyle drop-down opens a list of different VisualStyle enumeration options, such as System, Office2007Blue, Office2007Black, Office2007Silver, Custom, Office2010Blue, Office2010Black, and Office2010Silver. The default value is Custom. For more information on how to set the VisualStyle property, see Applying Visual Styles to C1ColorPicker and Customizing Appearance Using Visual Styles.

About C1.Win.C1Input

Clicking the About C1.Win.C1Input link displays the ComponentOne dialog box, which is helpful in finding the information about the version number, licensing, and online resources of the control.

C1FontPicker Tasks Menu

In the C1FontPicker Tasks menu, you can quickly and easily set the VisualStyle property for the C1FontPicker control. To access the C1FontPicker Tasks menu, click on the smart tag ( ) in the upper-right corner of the control. This will open the C1FontPicker Tasks menu.

The C1FontPicker Tasks menu operates as follows:

VisualStyle

Clicking the drop-down arrow in the VisualStyle drop-down opens a list of different VisualStyle enumeration options, such as System, Office2007Blue, Office2007Black, Office2007Silver, Custom, Office2010Blue, Office2010Black, and Office2010Silver. The default value is Custom. For more information on how to set the VisualStyle property, see Applying Visual Styles to C1FontPicker and Customizing Appearance Using Visual Styles.

About C1.Win.C1Input

Clicking the About C1.Win.C1Input link displays the ComponentOne dialog box, which is helpful in finding the information about the version number, licensing, and online resources of the control.

Using the C1Input Controls

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

C1Input Controls

The current version of C1Input contains twelve controls:

C1Button

A standard button type control derived from the standard System.Windows.Forms.Button. The C1Button control supports additional visual styles.

C1CheckBox

A window control used for setting or changing the value of an item as true, false, or indeterminate. The default C1CheckBox control is a two-state checkbox, but can be a three-state checkbox when the ThreeState property is enabled. The property CheckState determines the appearance of the checkbox state. The following table describes the three check box states and how it visually affects each checkbox.

Checkbox Description State Indeterminate A dark shaded gray box appears in the box when only a few of the checkbox items are selected.

Checked A checkmark appears in the checkbox item when the item is selected.

Unchecked An empty checkbox appears in the checkbox when the item is not selected.

The following image displays each check box state for the C1CheckBox control: indeterminate, checked, and unchecked.

C1ComboBox

A composite combobox control that allows users to view a drop-down list of options and select one or more options from the list.

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.

C1DropDownControl

A control derived from C1TextBox, C1DropDownControl supports all C1TextBox formatting, validation, and other features. Like the other two C1TextBox-derived controls, it also supports UpDown (spin) and drop-down buttons. However, unlike those specialized controls, C1DropDownControl allows you to attach your own logic to the UpDown button and your own drop-down form/editor to the drop-down button.

C1DateEdit

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

C1DbNavigator

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

C1Label

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

C1NumericEdit

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

C1PictureBox

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

C1RangeSlider

A control built on top of System.Windows.Forms.Control, C1RangeSlider enables numeric data selection over a range. The range is defined by two thumbs- upper value thumb and lower value thumb, which move over a Range Bar.

C1SplitButton

A composite button control supporting additional visual styles and drop down item list.

C1DbNavigator Control Overview

The C1DbNavigator class represents the C1DbNavigator control. It is a data bound control that 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. The NavigatorButtonEnum gets the list of available buttons for the C1DbNavigator control which are the following: Add, Apply, Cancel, Delete, Edit, First, Last, Next, Position, Previous, Refresh, and Update. The Position value of the NavigatorButtonEnum is used in the BeforeAction event when the text in Position text box is changed. For an example see, Changing the Navigation in the Navigator. The C1DbNavigator control includes the following buttons that can be used to navigate and edit the records in a dataset:

Button Description First button. Moves to the first row in the record. Visible by default.

Previous button. Moves to the previous row in the record. Visible by default.

Next button. Moves to the next row in the record. Visible by default.

Last button. Moves to the last row in the record. Visible by default.

Add button. Adds a row to the record. Not visible by default.

Delete button. Deletes the row in the record. Not visible by default.

Edit button. Edits the row in the record. Not visible by default.

Apply button. Applies the changes made in the record. Not visible by default.

Cancel button. Cancels the changes. Not visible by default.

Update button. Updates the record. Not visible by default.

Refresh button. Refreshes the record. Not visible by default.

C1DbNavigator Appearance

C1DbNavigator’s buttons, border, and user interface strings can easily be customized by using C1DbNavigator’s properties. C1DbNavigator’s Button Properties The following table lists and describes the properties used to customize the buttons on the C1DbNavigator control:

Property Description C1DbNavigator.ButtonSize The size of the navigator buttons.

C1DbNavigator.ButtonStyle Gets the navigator button style which can be flat or standard.

C1DbNavigator.ButtonTextAlign Controls how the text is positioned relative to the image in the navigator buttons.

C1DbNavigator.ButtonTexts Gets or sets the texts displayed on the buttons.

C1DbNavigator.ButtonToolTips The string collection defining the navigator button tooltips.

C1DbNavigator.ColorButtons Specifies if navigator buttons have color

bitmaps.

C1DbNavigator.ColorWhenHover If true, navigator buttons show color bitmaps when the mouse hovers over them.

C1DbNavigator.VisibleButtons Specifies which buttons are visible.

C1DbNavigator’s User Interface Strings The following table lists and describes the properties used to customize the user interface strings on the C1DbNavigator:

UIString Description Row: Represents the current selected row number in the record.

of {0} Represents the total amount of rows in the record.

(inactive) Represents the position textbox where the text is displayed.

(empty)

Confirmation Appears in the title of the dialog box that appears when you click on the delete button to delete a row in the record.

Do you want to Appears in the content area of the confirmation dialog box. delete the row?

C1DbNavigator Position Textbox Property You can use the Text property to get or set the text in the position textbox. If the Position textbox is not visible, it returns empty string. If you set the Text property when the Position textbox is not visible, the action has no effect. Changing the Text property causes the data source position change.

C1DbNavigator Behavior

C1DbNavigator’s includes several events for controlling its behavior. For example, the C1DbNavigator’s behavior can change when any of the buttons are pressed, if the current row or if the fields have been changed in the record, if there is an exception thrown when clicking one of its buttons, or if the visual property style has changed. The following table lists the C1DbNavigator events:

Event Description Adding Occurs when the Add button is pressed.

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 Event fired when the value of the ButtonCursor property is changed.

Deleting Occurs when the Delete button is pressed.

Editing Occurs when the Edit button is pressed.

Error Occurs when an exception 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 Refresh button is pressed.

TextChanged Occurs when the C1.Win.C1Input.C1DbNavigator.Text property value changes.

UpdateData Occurs when Update button is pressed.

VisualStyleChanged Occurs when the VisualStyle property has changed.

C1ComboBox Control Overview

C1ComboBox is a composite control that is used for displaying a list of selectable items. It functions similar to the ListBox control, but it takes up less space since the items can be hidden. Items can be added to the C1ComboBox through the Items property or they could be bound to data via an arrary of strings or binding source. C1ComboBox includes the following elements: Textbox, Button, and DropDownList. In the textbox you can type anything or you can click the button to select an item from the DropDownList. For more information see C1ComboBox Elements. In its default state the C1ComboBox control appears collapsed and only displays one item inside the textbox area. In its expanded state the C1ComboBox control appears expanded and displays a dropdown listbox of selectable items. The following image illustrates the C1ComboBox in its collapsed and expanded states:

In a typical combobox control, a dropdown button appears to the right and functions as a dropdownlist where you can quickly choose from a list of options. However, in C1ComboBox you can add more functionality and create a numeric up/down button to edit numeric values or you can add a modal button if you need to show a modal dialog in your combobox. For more information see C1ComboBox Button Appearance.

C1ComboBox Elements

This section provides a visual and descriptive overview of the elements that comprise the C1ComboBox control. The C1ComboBox control is made up of an editable text box and drop-down list.

C1ComboBox Text Box Users can enter text in the C1ComboBox textbox at runtime or you can assign strings to the Text property. If you assign a value to the Text property, the current value in the textbox of the C1ComboBox will changes. As text is entered into the C1ComboBox textbox, C1ComboBoxItems matching the characters will appear in the drop- down list. For example, if you enter "Sm" in the text box for a C1ComboBox listing customer names, any customer names starting with "Sm" appear in the drop-down list. C1ComboBox DropDown Button The default C1ComboBox displays a dropdown style button, but you can choose whether or not to show the button through the VisibleButtons property. In addition to the dropdown button you could also display the Updown button or your own custom button. A modal button can be displayed next to the dropdown, updown, or custom button or you can display it separately. For more information see C1ComboBox Button Appearance. The size of the button can be modified using the ButtonWidth property. Drop-down List of C1ComboBoxItems The drop-down list is made up of C1ComboBoxItems and is only visible at run time. You can access the drop-down list by clicking the trigger button, or drop-down arrow, next to the C1ComboBox text box. Items can be added to the C1ComboBox at design time through the String Collection Editor. In the String Collection Editor you can type the items line-by-line. Items could also be added dynamically during runtime through the Items property. For an example see, Adding Items to C1ComboBox.

ComboBox Item Modes

You can use the ItemMode property to build item presentation. There are three options which include the following: Default In the default option, each C1ComboBoxItem is a string and can also be an image. The following image illustrates a C1ComboBox with the Default option:

For an example see the ComboBoxImages sample. HtmlPattern In the HtmlPattern, each item is built from a HTML pattern and bound item data. The following image illustrates a C1ComboBox with the HtmlPattern:

The HtmlPattern used above is set to the following:

Country:	{Text}
Flag:

For an example see the ComboBoxItemModes sample. Html In the Html option, each item is a fragment of a HTML subset. The following image illustrates a C1ComboBox with the Html option:

The Html used above is set to the following: For an example see the ComboBoxItemModes sample.

C1ComboBox Styling

If you are not using one of the predefined themes you can set the C1ComboBox's VisualStyle property to Custom to create your own style for the C1CombBox control. C1ComboBox includes the following apppearance properties:

Property Description DefaultItemForeColor Gets or sets the default text color for the items in the C1ComboBox.

DropDownBackColor Gets or sets the background color for the dropdown form in the C1ComboBox.

DropDownBorderColor Gets or sets the border color for the dropdown form in the C1ComboBox.

HotItemBackColor Gets or sets the background color of the combobox items when you mouse over them.

HotItemBorderColor Gets or sets the border color for the combobox items when mouse over the border.

HotItemForeColor Gets or sets the forecolor for the combobox items when you mouse over them.

Padding Gets or sets the padding within the dropdown form.

TextSpacing Gets or sets the textual parts of the combobox items.

C1ComboBox Button Appearance

The default C1ComboBox appears with one dropdown button to the right of the textbox. You can determine the button's visibility and what type of button to use through the C1ComboBox.VisibleButtons property. The C1ComboBox.VisibleButtons property provides the following possible values:

Value Appearance or Description None C1ComboBox appears with no dropdown button.

UpDown Gets or sets the background color for the dropdown form in the C1ComboBox.

DropDown Displays the default image for the DropDown button.

Modal Displays ther default image for the Modal button. It appears to the right of the dropdown button if the dropdown button is enabled too.

Custom Gets or sets the custom button for the C1ComboBox control.

Once the button style is determined you can use the default button image for the selected button or you can create a custom image for it. The following properties can be used to apply the custom image for each button style (Custom, UpDown, DropDown, and Modal):

ButtonImages.CustomImage - Applies the image to the Custom button. ButtonImages.DownImage - Applies the image to the Down button. ButtonImages.DropImage - Applies the image to the DropDown button. ButtonImages.ModalImage - Applies the image to the Modal buton. ButtonImages.Up - Applies the image to the Up button.

ComboBox DataBinding

C1ComboBox can be bound to an Enum and an Array at runtime or it can be bound at design time through an array or strings or bindingsource. Binding C1ComboBox to data gives you the ability to browse data in a database, enter new data, or add existing data. The C1ComboBoxFeatures sample shows how to use the following different methods for binding data to C1CombBox:

How to bind C1ComboBox to an Enum at runtime How to bind C1ComboBox to an Array at runtime How to bind C1ComboBox to an Array at design time How to bind C1ComboBox to a bindingsource

Adding Images to Items in the ComboBox

You can easily use the images from the ImageList to add images to each item in the dropdown list of a C1ComboBox control. To add images to C1ComboBoxItems at Design time, complete the following:

1. Add the C1ComboBox control to your form. 2. Add items to C1ComboBox.Items collection using the String Collection Editor. 3. Add the ImageList control to your form. 4. Add images to the imageList1. 5. Set keys (Name) of the images equal to the items in C1ComboBox.Items.

To add images to C1ComboBoxItems at Run time, add the following code: To write code in Visual Basic

Visual Basic c1ComboBox1.ItemsImageList = imageList imageList.Images.Add("First item", Image.FromFile("First.png")) c1ComboBox1.Items.Add("First item")

To write code in C#

C# c1ComboBox1.ItemsImageList = imageList; imageList.Images.Add("First item", Image.FromFile("First.png")); c1ComboBox1.Items.Add("First item");

Adding Items to C1ComboBox

You can easily add items to C1ComboBox programatically using the Add method or you can add them at design time through the String Collection Editor. If you have more than one item, the Add method will add the new item(s) in the next position. If you need to add an item or object at a specific position in the list you can use the Insert method. An entire array can be added to the ComboBox by using the AddRange method to add the object or string of items to the C1ComboBox. To Add Items Programatically To add items to the C1ComboBox using the Add method of the C1ComboBox class. The collection is referenced using the Items property. To write code in Visual Basic

Visual Basic c1ComboBox1.Items.Add("Pittsburgh")

To write code in C#

C# c1ComboBox1.Items.Add("Pittsburgh");

To Add Items Using the String Collection Editor

1. On the form, right-click on the C1ComboBox control and select Edit Items. The String Collection Editor appears. 2. In the String Colllection Editor, enter the string and then press Enter to add the next string in position.

To Insert the String or Object at the Desired Position The following example inserts the string, Chicago, in the fifth position:

To write code in Visual Basic

Visual Basic c1ComboBox1.Items.Insert(4, "Chicago")

To write code in C#

C# c1ComboBox1.Items.Insert(4, "Chicago");

To Pass an Array through Strings To pass an array through strings, complete the following:

1. Add the C1ComboBox control to the Form. 2. Add a Button control to the Form. 3. Create the following Button_Click event handler and add the following code to pass the array through strings to the C1ComboBox:

To write code in Visual Basic

Visual Basic Type your Drop Down Section text here.

C# private void button1_Click(object sender, EventArgs e) { string[] items = { "FreeStyle Stroke", "Back Stroke", "ButterFly Stroke", "Breast Stroke"}; c1ComboBox1.Items.AddRange(items); }

4. Run your project and click on the Button. 5. Click on the dropdown button on the C1ComboBox control and notice the string of items appear in the dropdownlist:

Removing Items from C1ComboBox

All Items or specific items can easily be removed from the C1ComboBox programmatically or at design time through

the Strings Collection Editor. Removing All Items Programatically To programatically remove all items from C1ComboBox, complete the following: To write code in Visual Basic

Visual Basic c1ComboBox1.Items.Clear()

To write code in C#

C# c1ComboBox1.Items.Clear();

Removing an Item Programatically To programatically remove an item use the Remove or RemoveAt methods. The Remove method removes the specified item or selected item. The RemoveAt method removes the item with the specified index number. The following code shows how to use the Remove and RemoveAt methods to remove specific items or remove selected items: To write code in Visual Basic

Visual Basic ' To remove item with index 0: c1ComboBox1.Items.RemoveAt(0) ' To remove currently selected item: c1ComboBox1.Items.Remove(ComboBox1.SelectedItem) ' To remove "Chicago" item: c1ComboBox1.Items.Remove("Chicago")

To write code in C#

C# // To remove item with index 0: comboBox1.Items.RemoveAt(0); // To remove currently selected item: comboBox1.Items.Remove(comboBox1.SelectedItem); // To remove "Chicago" item: comboBox1.Items.Remove("Chicago");

Populating C1ComboBox with Data Using SelectedItemChanged Event To populate the C1ComboBox with data once a specific item in the combobox has been selected, use the SelectedItemChanged event like the following:

1. Add two C1ComboBoxes on the Form.

2. Add the string, "Pittsburgh", to the first C1ComboBox using the String Collection Editor. 3. Double click on the SelectedItemChanged event in C1ComboBox Properties window to create an event handler for the SelectedItemChanged event. 4. Add the following code to the SelectedIndexChanged event:

To write code in Visual Basic

Visual Basic Private Sub comboBox1_SelectedItemChanged(sender As Object, e As EventArgs) c1ComboBox2.Items.Clear() If c1ComboBox1.SelectedItem.ToString() = "Pittsburgh" Then c1ComboBox2.Items.Add("Pittsburgh is known as the Steel City and the City of Bridges.") c1ComboBox2.Items.Add("Pittsburgh has 446 Bridges") Else c1ComboBox2.Items.Add("You did not select Pittsburgh.") End If End Sub

To write code in C#

C# private void comboBox1_SelectedItemChanged(object sender, EventArgs e) { c1ComboBox2.Items.Clear(); if (c1ComboBox1.SelectedItem.ToString() == "Pittsburgh") { c1ComboBox2.Items.Add("Pittsburgh is known as the Steel City and the City of Bridges."); c1ComboBox2.Items.Add("Pittsburgh has 446 Bridges"); } else { c1ComboBox2.Items.Add("You did not select Pittsburgh.");

} }

5. Run your project and select Pittsburgh in the first C1ComboBox. 6. Click on the dropdown button in the second C1ComboBox and notice the items were added to the dropdownlist based on what you added in the SelectedItemChanged event.

Populating C1Combbox with Data Using the SelectedIndexChanged Event To populate the C1ComboBox with data once a specific index in the combobox has been selected, use the SelectedIndexChanged event like the following:

1. Add two C1ComboBoxes on the Form. 2. In the first C1ComboBox add the items line by line in the String Collection Editor so it appears like the following:

3. Double click on the SelectedIndexChanged event in the C1ComboBox Properties window to create an event handler for the SelectedIndexChanged event. 4. Add the following code to the SelectedIndexChanged event:

To write code in Visual Basic

Title Text Private Sub comboBox1_SelectedIndexChanged(sender As Object, e As EventArgs) c1ComboBox2.Items.Clear() If c1ComboBox1.SelectedIndex.ToString() = "1" Then c1ComboBox2.Items.Add("You selected the second item.") Else c1ComboBox2.Items.Add("You did not select the second item.") End If

End Sub

To write code in C#

C# private void comboBox1_SelectedIndexChanged(object sender, EventArgs e) { c1ComboBox2.Items.Clear(); if (c1ComboBox1.SelectedIndex.ToString() == "1") { c1ComboBox2.Items.Add("You selected the second item.");

} else { c1ComboBox2.Items.Add("You did not select the second item."); } }

4. Run your project and select the first index or second item, "Orlando" in the first C1ComboBox. 5. Click on the dropdown button in the second C1ComboBox and notice the items were added to the dropdownlist based on what you added in the SelectedIndexChanged event.

C1RangeSlider Control Overview

C1RangeSlider is a simple control that enables you to select a range of numeric data with lower value thumb and upper value thumb. These thumbs define start and end values of the range. When you drag the thumb towards the left (or down) on Range Bar you reduce its value, and you increase the value when drag it towards the right (or up). The control has minimum and maximum bounds for thumb values. Thumb value cannot be less than the minimum bound and more than the maximum bound. Moreover, lower value cannot be greater than the upper value, and otherwise. The control can be oriented horizontally or vertically.

C1RangeSlider Elements

When you add C1Range Slider control to your form it exists as a completely functional slider control, with two thumbs to set range values and a range bar on which the thumbs move.

C1RangeSlider Features

This section describes key features of C1RangeSlider control.

Maximum and Minimum Values

The Maximum and Minimum properties enable you to set upper and lower allowable bounds for range in C1RangeSlider control. Lower value thumb cannot be set to a value less than the Minimum, and Upper Value thumb cannot be set to a value greater than the Maximum. By default Minimum is set to 0 and Maximum is set to 100. Set the Minimum and Maximum values using Minimum and Maximum properties from Properties pane of the control, or through code: To write code in Visual Basic

Visual Basic Me.c1RangeSlider1.Minimum = 10 Me.c1RangeSlider1.Maximum = 100

To write code in C#

C# this.c1RangeSlider1.Minimum = 10; this.c1RangeSlider1.Maximum = 100;

Orientation

C1RangeSlider control can be displayed Horizontally or Vertically, using Orientation property. By default, the control is oriented horizontally.

You can easily change the orientation through Orientation property in Properties pane, or through code: To write code in Visual Basic

Visual Basic Me.c1RangeSlider1.Orientation = Orientation.Vertical

To write code in C#

C# this.c1RangeSlider1.Orientation = Orientation.Vertical;

Thumb Values and Range

Range in C1RangeSlider control is the difference between UpperValue and LowerValue properties. These two values are linked with movable thumbs which are used to set the numeric range on the control.

Setting the Thumb Values Thumb values can be set using UpperValue and LowerValue properties in properties pane or through code. By default, the UpperValue property is set to 100, and LowerValue property is set to 0. To write code in Visual Basic

Visual Basic Me.c1RangeSlider1.LowerValue = 24 Me.c1RangeSlider1.UpperValue = 88

To write code in C#

C# this.c1RangeSlider1.LowerValue = 24; this.c1RangeSlider1.UpperValue = 88;

C1RangeSlider Appearance

You can customize the appearance of C1RangeSlider control by adjusting background image, thumb style and range bar style.

Background Image

Complete the following steps to set background image to C1RangeSlider control:

1. In Solution Explorer, right-click the project name and select Add > New Folder. 2. Rename the folder Resources. 3. Add the desired image to the Resources folder of your local project. 4. In Solution Explorer, click the Show All Files( ) button. 5. Right-click the image kept in Resources folder and select Include In Project. 6. Right-click C1RangeSlider control and select Properties. 7. In the Properties pane expand the Appearance node. 8. Click the ellipsis( ) button next to BackgroundImage property. Select Resources dialog box appears. 9. Click the Import button and browse to Resources folder in your project. 10. Select the image and click OK to save and close the Select Resource dialog box.

Setting the Background Image Layout

1. In Properties pane, click the dropdown corresponding to BackgroundImageLayout property. 2. Select the appropriate layout for the background image of your C1RangeSlider control.

Bar Style

You can manage the appearance of C1RangeSlider control through various Bar Style options.

BackColor

Back color of C1RangeSlider bar can be changed at design time or through code. To change the back color in design time complete the following:

1. Right-click the C1RangeSlider control and select Properties option. 2. In Properties pane expand the Styles node. 3. Select BackColor property from BarStyle collection. 4. In the drop-down menu corresponding to BackColor property, select Lavender.

To change the back color at run-time, add the following code in FormLoad event: To write code in Visual Basic

Visual Basic Me.C1RangeSlider1.Styles.BarStyle.BackColor = System.Drawing.Color.Lavender

To write code in C#

C# this.c1RangeSlider1.Styles.BarStyle.BackColor = System.Drawing.Color.Lavender;

BorderColor

To change the border color in design time complete the following:

1. Right-click the C1RangeSlider control and select Properties option. 2. In Properties pane expand the Styles node. 3. Select BorderColor property from BarStyle collection. 4. In the drop-down menu corresponding to BorderColor property, select MediumBlue.

To change the border color at run-time, add the following code in FormLoad event: To write code in Visual Basic

Visual Basic Me.C1RangeSlider1.Styles.BarStyle.BorderColor = System.Drawing.Color.MediumBlue

To write code in C#

C# this.c1RangeSlider1.Styles.BarStyle.BorderColor = System.Drawing.Color.MediumBlue;

Run your project and observe the customizations. Following image shows the changed back color and border color of range bar in C1RangeSlider control:

DisabledBackColor

DisabledBackColor property enables you to set the background color of range bar, which will be visible when the C1RangeSlider control is disabled. To change the DisabledBackColor in design time complete the following:

1. Right-click the C1RangeSlider control and select Properties option. 2. In Properties pane expand the Styles node. 3. Select DisabledBackColor property from BarStyle collection. 4. In the drop-down menu corresponding to DisabledBackColor property, select ScrollBar.

To change the DisabledBackColor at run-time, add the following code in FormLoad event: To write code in Visual Basic

Visual Basic Me.C1RangeSlider1.Styles.BarStyle.DisabledBackColor = System.Drawing.SystemColors.ScrollBar

To write code in C#

C# this.c1RangeSlider1.Styles.BarStyle.DisabledBackColor = System.Drawing.SystemColors.ScrollBar;

DisabledBorderColor

DisabledBorderColor property enables you to set the border color of range bar, which will be visible when the C1RangeSlider control is disabled. To change the DisabledBorderColor in design time complete the following:

1. Right-click the C1RangeSlider control and select Properties option. 2. In Properties pane expand the Styles node. 3. Select DisabledBorderColor property from BarStyle collection. 4. In the drop-down menu corresponding to DisabledBorderColor property, select Red.

To change the DisabledBorderColor at run-time, add the following code in FormLoad event: To write code in Visual Basic

Visual Basic Me.C1RangeSlider1.Styles.BarStyle.DisabledBorderColor = System.Drawing.Color.Red

To write code in C#

C# this.c1RangeSlider1.Styles.BarStyle.DisabledBorderColor = System.Drawing.Color.Red;

Set the Enabled property to False, and run the project. Following image shows disabled back color and disabled border color of range bar in the C1RangeSlider control:

Thumb Style

You can manage the appearance of C1RangeSlider control through various Thumb Style options.

Back Color

Back color of C1RangeSlider thumbs can be changed at design time or through code To change the back color in design time complete the following:

1. Right-click the C1RangeSlider control and select Properties option. 2. In Properties pane expand the Styles node.

3. Select BackColor property from ThumbStyle collection. 4. In the drop-down menu corresponding to BackColor property, select Tan.

To change the Back Color at run-time, add the following code in FormLoad event: To write code in Visual Basic

Visual Basic Me.C1RangeSlider1.Styles.ThumbStyle.BackColor = System.Drawing.Color.Tan

To write code in C#

C# this.c1RangeSlider1.Styles.ThumbStyle.BackColor = System.Drawing.Color.Tan;

Border Color

Border color of C1RangeSlider thumbs can be changed at design time or through code To change the back color in design time complete the following:

1. Right-click the C1RangeSlider control and select Properties option. 2. In Properties pane expand the Styles node. 3. Select BorderColor property from ThumbStyle collection. 4. In the drop-down menu corresponding to BorderColor property, select ActiveCaptionText.

To change the Border Color at run-time, add the following code in FormLoad event: To write code in Visual Basic

Visual Basic Me.C1RangeSlider1.Styles.ThumbStyle.BorderColor = System.Drawing.SystemColors.ActiveCaptionText

To write code in C#

C# this.c1RangeSlider1.Styles.ThumbStyle.BorderColor = System.Drawing.SystemColors.ActiveCaptionText;

Corner Radius

CorneRadius property enables you to customise the appearance of thumbs of C1RangeSlider control. Thumbs with CornerRadius set to 0 will be rectangular. To add curvature to the thumbs, you can increase their corner radius. Corner Radius of C1RangeSlider thumbs can be changed at design time or through code To change CornerRadius of thumbs in design time complete the following:

1. Right-click the C1RangeSlider control and select Properties option. 2. In Properties pane expand the Styles node. 3. Select CornerRadius property from ThumbStyle collection. 4. Set CornerRadius to 4.

To change the Corner Radius at run-time, add the following code in FormLoad event:

To write code in Visual Basic

Visual Basic Me.C1RangeSlider1.Styles.ThumbStyle.CornerRadius = 4

To write code in C#

C# this.c1RangeSlider1.Styles.ThumbStyle.CornerRadius = 4;

The following image shows customised thumb styles of C1RangeSlider control with corner radius 4.

Disabled Back Color

DisabledBackColor property enables you to set the background color of thumb, which will be visible when the C1RangeSlider control is disabled. DisabledBackColor of C1RangeSlider thumbs can be changed at design time or through code To change the DisabledBackColor in design time complete the following:

1. Right-click the C1RangeSlider control and select Properties option. 2. In Properties pane expand the Styles node. 3. Select DisabledBackColor property from ThumbStyle collection. 4. In the drop-down menu corresponding to DisabledBackColor property, select InactiveCaption.

To change the DisabledBackColor at run-time, add the following code in FormLoad event: To write code in Visual Basic

Visual Basic Me.C1RangeSlider1.Styles.ThumbStyle.DisabledBackColor = System.Drawing.SystemColors.InactiveCaption

To write code in C#

C# this.c1RangeSlider1.Styles.ThumbStyle.DisabledBackColor = System.Drawing.SystemColors.InactiveCaption;

Disabled Border Color

DisabledBorderColor property enables you to set the border color of thumbs, which will be visible when the C1RangeSlider control is disabled. DisabledBorderColor of C1RangeSlider thumbs can be changed at design time or through code. To change the DisabledBorderColor in design time complete the following:

1. Right-click the C1RangeSlider control and select Properties option. 2. In Properties pane expand the Styles node. 3. Select DisabledBorderColor property from ThumbStyle collection.

4. In the drop-down menu corresponding to DisabledBorderColor property, select WindowFrame.

To change the DisabledBorderColor at run-time, add the following code in FormLoad event: To write code in Visual Basic

Visual Basic Me.C1RangeSlider1.Styles.ThumbStyle.DisabledBorderColor = System.Drawing.SystemColors.WindowFrame

To write code in C#

C# this.c1RangeSlider1.Styles.ThumbStyle.DisabledBorderColor = System.Drawing.SystemColors.WindowFrame;

The following image shows customised thumb styles in disabled C1RangeSlider control.

Hovered Back Color

HoveredBackColor property enables you to set the back color of thumbs, which will be visible when mouse is over it. HoveredBackColor of C1RangeSlider thumbs can be changed at design time or through code To change the HoveredBackColor in design time complete the following:

1. Right-click the C1RangeSlider control and select Properties option. 2. In Properties pane expand the Styles node. 3. Select HoveredBackColor property from ThumbStyle collection. 4. In the drop-down menu corresponding to HoveredBackColor property, select ActiveCaption.

To change the HoveredBackColor at run-time, add the following code in FormLoad event: To write code in Visual Basic

Visual Basic Me.C1RangeSlider1.Styles.ThumbStyle.HoveredBackColor = System.Drawing.SystemColors.ActiveCaption

To write code in C#

C# this.c1RangeSlider1.Styles.ThumbStyle.HoveredBackColor = System.Drawing.SystemColors.ActiveCaption;

Hovered Border Color

HoveredBorderColor property enables you to set the border color of thumbs, which will be visible when mouse is over it. HoveredBackColor of C1RangeSlider thumbs can be changed at design time or through code

To change the HoveredBorderColor in design time complete the following:

1. Right-click the C1RangeSlider control and select Properties option. 2. In Properties pane expand the Styles node. 3. Select HoveredBorderColor property from ThumbStyle collection. 4. In the drop-down menu corresponding to HoveredBorderColor property, select Blue.

To change the HoveredBorderColor at run-time, add the following code in FormLoad event: To write code in Visual Basic

Visual Basic Me.C1RangeSlider1.Styles.ThumbStyle.HoveredBorderColor = System.Drawing.Color.Blue

To write code in C#

C# this.c1RangeSlider1.Styles.ThumbStyle.HoveredBorderColor = System.Drawing.Color.Blue;

The following image shows customised thumb styles of C1RangeSlider control on mouse over.

Pressed Back Color

PressedBackColor property enables you to set the back color of thumbs, which will be visible when mouse-click is performed over it. PressedBackColor of C1RangeSlider thumbs can be changed at design time or through code To change the PressedBackColor in design time complete the following:

1. Right-click the C1RangeSlider control and select Properties option. 2. In Properties pane expand the Styles node. 3. Select PressedBackColor property from ThumbStyle collection. 4. In the drop-down menu corresponding to PressedBackColor property, select Gold.

To change the PressedBackColor at run-time, add the following code in FormLoad event: To write code in Visual Basic

Visual Basic Me.C1RangeSlider1.Styles.ThumbStyle.PressedBackColor = System.Drawing.Color.Gold

To write code in C#

C# this.c1RangeSlider1.Styles.ThumbStyle.PressedBackColor = System.Drawing.Color.Gold;

Pressed Border Color

PressedBorderColor property enables you to set the border color of thumbs, which will be visible when mouseclick is performed over it.

PressedBorderColor of C1RangeSlider thumbs can be changed at design time or through code To change the PressedBorderColor in design time complete the following:

1. Right-click the C1RangeSlider control and select Properties option. 2. In Properties pane expand the Styles node. 3. Select PressedBorderColor property from ThumbStyle collection. 4. In the drop-down menu corresponding to PressedBorderColor property, select Orange.

To change the PressedBorderColor at run-time, add the following code in FormLoad event: To write code in Visual Basic

Visual Basic Me.C1RangeSlider1.Styles.ThumbStyle.PressedBorderColor = System.Drawing.Color.Orange

To write code in C#

C# this.c1RangeSlider1.Styles.ThumbStyle.PressedBorderColor = System.Drawing.Color.Orange;

The following image shows customised thumb styles of C1RangeSlider control when mouse-click is performed.

C1ColorPicker Control Overview

C1ColorPicker control is a color input editor that provides an interactive color selection interface. Users can select basic colors and can define custom colors from various options available in the C1ColorPicker to create a polished and professional looking application. C1ColorPicker also supports additional visual styles and themes that help users in further customizing their applications.

C1ColorPicker Elements

The C1ColorPicker control exists as a complete color selection control that you can customize further. When you click the drop-down button available on the C1ColorPicker, the control's interface looks similar to the following image:

The ellipses on the right of drop-down button let you select the basic colors that available in the color picker.

You can also define custom colors by clicking the Default Custom Colors button, creating a custom color from the color palette, and then adding the defined color to custom colors.

Working with C1ColorPicker

This topic illustrates how to use C1ColorPicker in Windows Forms applications. The steps to set up Visual Studio project and customize the application during runtime are as follows:

1. Create a Windows Forms project and add C1ColorPicker control to the Form. 2. Add a RichTextBox control to the Form. Set the Text property of the RichTextBox to TextColor. The Form appears like the image shown below:

3. Set the Color property of the C1ColorPicker control to a desired color from the palette. This enables the user to set a particular color as the current color instead of the default Transparent. 4. Add the following code to the C1ColorPicker1_ValueChanged event handler to change the color of the text on color selection: VB

Private Sub C1ColorPicker1_ValueChanged(sender As Object, e As EventArgs) Handles C1ColorPicker1.ValueChanged RichTextBox1.SelectionColor = DirectCast(DirectCast(sender, C1ColorPicker).Value, Color) End Sub

C# private void c1ColorPicker1_ValueChanged(object sender, EventArgs e) { richTextBox1.SelectionColor = (Color)c1ColorPicker1.Value; } 5. Run the application. Now you can select the color from the drop-down of the C1ColorPicker and set the color of the text in the RichTextBox control. The following image shows the output where the text is set as red.

Applying Visual Styles to C1ColorPicker

Visual styles can be applied to the C1ColorPicker control using VisualStyle property. The smart tag on the top right corner of C1ColorPicker control lets users select the visual style they want to apply on the color picker.

To Change the Visual Style using the Smart Tag

Complete the following steps:

1. Select the C1ColorPicker control. 2. Click the smart tag ( ) to open the C1ColorPicker Tasks menu. 3. Click the visual style drop-down arrow and select a visual style to apply on the C1ColorPicker control.

To Change the Visual Style through Code

The code snippets refer the color picker application created in Working with C1ColorPicker.

1. Add the ComboBox control to the form. 2. Add the following line of code to the application to get the visual styles in the ComboBox: VB InitializeComponent() ComboBox1.DataSource = [Enum].GetValues(GetType(VisualStyle))

C# InitializeComponent(); comboBox1.DataSource = Enum.GetValues(typeof(VisualStyle)); 3. Add code to the comboBox1_SelectedIndexChanged event handler so that the visual style of C1ColorPicker is updated on selecting an option from the combo box listing the available visual styles: VB Private Sub ComboBox1_SelectedIndexChanged(sender As Object, e As EventArgs) Handles ComboBox1.SelectedIndexChanged C1ColorPicker1.VisualStyle = DirectCast(ComboBox1.SelectedItem, VisualStyle) End Sub

C# private void comboBox1_SelectedIndexChanged(object sender, EventArgs e) { c1ColorPicker1.VisualStyle = (VisualStyle)comboBox1.SelectedItem;

} 4. Run the application. Now you can select the visual style from the drop down of the combo box and set the visual style of the C1ColorPicker. The following image shows the output:

C1FontPicker Control Overview

C1FontPicker control is a font selection control that lets users select the desired font from a drop-down list. Users can select out of a list of more than 250 fonts available in the C1FontPicker. The C1FontPicker also supports additional visual styles and themes to choose from so that the users can further customize their applications.

C1FontPicker Elements

C1FontPicker control is a font selection control and when you click the drop-down button on C1FontPicker, the control's interface looks similar to the following image:

You can browse through the list to see the available fonts .

Working with C1FontPicker

This topic illustrates how to use C1FontPicker for Windows Forms applications. The steps to set up Visual Studio project and customize the application during runtime are as follows:

1. Create a Windows Forms project and add C1FontPicker control to the Form. 2. Add RichTextBox control to the Form. Set the Text property of the RichTextBox to TextFontStyle. The Form appears like the image shown below:

3. Add the following code to the C1FontPicker1_ValueChanged event handler to change the font of the text on font selection: VB Private Sub C1FontPicker1_ValueChanged(sender As Object, e As EventArgs) Handles C1FontPicker1.ValueChanged RichTextBox1.SelectionFont = New Font(DirectCast(sender, C1FontPicker).Value.ToString(), RichTextBox1.SelectionFont.Size, RichTextBox1.SelectionFont.Style) End Sub

C# private void c1FontPicker1_ValueChanged(object sender, EventArgs e) { richTextBox1.SelectionFont = new Font(((C1FontPicker)sender).Value.ToString(), richTextBox1.SelectionFont.Size, richTextBox1.SelectionFont.Style); } 4. Run the application. Now you can select the font from C1FontPicker drop-down. The following image shows the output:

Applying Visual Styles to C1Font Picker

The smart tag on the top right corner of the C1FontPicker control lets users select the visual style of the C1FontPicker.

To Change the Visual Style using the Smart Tag

Complete the following steps:

1. Select the C1FontPicker control. 2. Click the smart tag ( ) to open the C1FontPicker Tasks menu. 3. Click the visual style drop-down arrow and select a visual style to apply on the C1FontPicker control.

To Change the Visual Style through Code

The code snippets refer the font picker application created in Working with C1FontPicker.

1. Add the ComboBox control to the form. 2. Add the following line of code to the application to get the visual styles in the ComboBox: VB InitializeComponent() ComboBox2.DataSource = [Enum].GetValues(GetType(VisualStyle))

C# InitializeComponent(); comboBox2.DataSource = Enum.GetValues(typeof(VisualStyle)); 3. Add code to the comboBox1_SelectedIndexChanged event handler so that the visual style of C1FontPicker is updated on selecting an option from the combo box listing visual styles available: VB Private Sub ComboBox2_SelectedIndexChanged(sender As Object, e As EventArgs) Handles ComboBox2.SelectedIndexChanged C1FontPicker1.VisualStyle = DirectCast(ComboBox2.SelectedItem, VisualStyle) End Sub

C# private void comboBox2_SelectedIndexChanged(object sender, EventArgs e) { c1FontPicker1.VisualStyle = (VisualStyle)comboBox2.SelectedItem; } 4. Run the application. Now you can select the visual style from the drop down of the combo box and set the visual style of the C1FontPicker. The following image shows the output:

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 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 DataObjects, see the C1DataObjects documentation included in the ComponentOne Studio Enterprise. DataObjects is a data framework, a part of ComponentOne Studio Enterprise, enhancing ADO.NET in many ways. To bind a C1Input control to a date source field: To bind a C1Input control to a data source field:

1. Assign the data source object to the control's DataSource property 2. Then assign a field of the data source object to the control’s DataField property.

You can set the DataSource and DataField properties in code as well as in the designer. 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.

3. Set the DataType property.

After you bind the control to a data field, 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 DataBindings to bind the control’s value to a field, use the DataSource and 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 property is set to True) in a properly formatted form, see Formatting Data for details. If the control is not read-only, it automatically switches to EditMode when it receives input focus, provided that TextDetached property is set to 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, (for instance, move the input focus elsewhere), the Value property is updated with the Text entered by the user. The process of updating the Value involves the following three main actions:

Parsing

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 for details.

Validation

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

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 property is set to 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 is controlled by the FormatType property, see Format Types for details. 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 property is set to "##,###.###" produces numbers with at most five digits before and three digits after decimal point. See Custom Format Specifiers 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 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 property is set to 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:

Formatting Option Description 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 to 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

The following table describes the custom numeric format specifiers:

Format Name Description Specifier 0 Zero If the value being formatted has a digit in the placeholder 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 If the value being formatted has a digit in the placeholder 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 The first '.' character in the format string point 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 The ',' character serves two purposes. First, if separator the format string contains a ',' character and between two digit placeholders (0 or #) and to number the left of the decimal point if one is present, scaling 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 The presence of a '%' character in a format placeholder 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- Scientific If any of the strings 'E', 'E+', 'E-', 'e', 'e+', or 'e-' 0 e0 e+0 notation are present in the format string and are e-0 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' Literal Characters enclosed in single or double "ABC" string quotes are copied to the output string literally, and do not affect formatting.

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

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

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

Examples

The following table displays examples using the custom numeric format specifiers:

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

The following table describes the custom date-time format specifiers:

Format Description Specifier 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 Displays the full name of the day for the specified DateTime any object. If a specific valid format provider (a non-null object number of that implements IFormatProvider with the expected property) additional is not supplied, then the DayNames property of the "d" DateTimeFormat object and its current culture associated with characters) 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 Displays the era (A.D. for example) for the specified DateTime (plus any object. If a specific valid format provider (a non-null object number of that implements IFormatProvider with the expected property) additional is not supplied, then the era is determined from the calendar "g" associated with the DateTimeFormat object and its current characters) 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 Displays the hour for the specified DateTime object in the (plus any range 1-12. The hour represents whole hours passed since number of either midnight (displayed as 12) or noon (also displayed as additional 12). If this format is used alone, then the same hour before or "h" after noon is indistinguishable. If the hour is a single digit (1- characters) 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 Displays the hour for the specified DateTime object in the (plus any range 0-23. The hour represents whole hours passed since number of midnight (displayed as 0). If the hour is a single digit (0-9), it is additional formatted with a preceding 0 (01-09). "H" characters) 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 Displays the minute for the specified DateTime object in the (plus any range 0-59. The minute represents whole minutes passed number of since the last hour. If the minute is a single digit (0-9), it is additional formatted with a preceding 0 (01-09). "m" characters)

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 Displays the seconds for the specified DateTime object in the any range 0-59. The second represents whole seconds passed number of since the last minute. If the second is a single digit (0-9), it is additional formatted with a preceding 0 (01-09). "s" characters) 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 Displays the A.M./P.M. designator for the specified DateTime any object. If a specific valid format provider (a non-null object number of that implements IFormatProvider with the expected property) additional is not supplied, then the AMDesignator (or PMDesignator) "t" property of the DateTimeFormat object and its current culture characters) 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 Displays the time zone offset for the system's current time (plus any zone in hours and minutes. The offset is always displayed with number of a leading or trailing sign (zero is displayed as '+00:00'), additional indicating hours ahead of Greenwich mean time (+) or hours "z" behind Greenwich mean time (-). The range of values is –12 to characters) +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 Other characters are written directly to the output string as character literals.

Examples

The following table displays examples using the custom date-time format specifiers:

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

Culture property

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 Current Culture, which is the current culture used by the application containing the control.

CultureInfo property

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

UserCultureOverride property

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 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, and so on.

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

Property Description 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 property is set to 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 CustomPlaceholders collection):

Placeholder Description # 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 property is set to 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 set to (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 for explanation of the validation process.

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 PreValidation property defines how the PatternString is interpreted.

Value Description 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 PreValidation 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) is performed.

Examples

The following examples describe how the Validation and PatternString properties are interpreted:

Validation property set to ExactList, PatternString property set to red|green|blue: Input string must be one of the three permitted values, red, green or blue, possibly ignoring the case, if CaseSensitive is set to False. Validation property set to Wildcards, PatternString property set to (412)*: Input string must start with (412), possibly ignoring the case, if CaseSensitive is set to False. Validation property set to RegexPattern, PatternString set to [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. The PostValidation class allows you to:

Check that the value matches one of the values in a pre-defined value list specified in the Values property. 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).

Exclude some values using the ValuesExcluded property. Perform validation programmatically in the PostValidating event.

To distinguish between declarative and programmatic validation, use the PostValidation 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 property is set to DateTime and DateTimeInput property is set to True (default). In the DateTimeInput mode, the currently selected date or time field, such as the year, month, date, and so on, 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. The UP ARROW/DOWN ARROW keys or mouse wheel can be used to increment/decrement the current field. Additional properties controlling date-time input are:

Property Description MinShortYear The minimum year that can be entered without leading zeros (when DateTimeInput is set to True). For example, if MinShortYear is set to 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 drop-down 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 the NumericInput property is set to 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 drop-down calculator and up/down buttons (speed buttons) incrementing/decrementing the value by the specified Increment.

Drop-Down and Increment Buttons

The specialized C1Input controls for date-time and numeric editing, C1DateEdit and C1NumericEdit controls, support drop-down and increment/decrement (up/down) buttons. Button visibility is controlled by the ShowDropDownButton and ShowUpDownButtons properties. To control drop-down alignment and distance from the control you can use the DropDownAlign and GapHeight properties. To open/close drop-down programmatically, use the OpenDropDown and CloseDropDown methods. Opening/closing drop-down triggers events DropDownOpened and DropDownClosed. You can use the DropDownOpened event to adjust drop-down properties (mostly, calendar properties in Calendar) before the drop- down is shown to the user. You can check if the drop-down is open using the DroppedDown property.

C1DateEdit Control

C1DateEdit control supports up/down buttons and drop-down calendar.

The up/down buttons function if DateTimeInput property is set to True. They increment/decrement the currently selected field of the date-time value, see Editing Date and Time Values. The drop-down calendar has the same object model as the standard MonthCalendar control (System.Windows.Forms.MonthCalendar) and almost the same appearance with additional buttons such as 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 in the designer and in code in the Calendar object. If you want to change calendar properties programmatically when the calendar is opened, before it is shown to the user, use the DropDownOpened event.

C1NumericEdit Control

C1NumericEdit control supports up/down (spin) buttons and drop-down calculator. Up/down buttons increment/decrement the Value by the amount specified in the Increment property (default: 1). The drop-down calculator follows the standard Windows calculator model, allows the user to perform calculations without leaving the control.

Custom Drop-Down

C1Input includes a powerful custom drop-down functionality that allows you to create any drop-down editor you need, in addition to the standard calendar and calculator drop-downs provided by C1Input. Drop-down editors are created visually as forms in your project. To create your own custom drop-down editor, use the C1DropDownControl. This control class derives from C1TextBox and adds custom drop-down functionality and up/down buttons. To create a drop-down editor for your control: 1. Add a form to your project derived from C1.Win.C1Input.DropDownForm and select the form class name in the DropDownFormClassName property of your C1DropDownControl. 2. 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 drop-down forms. Also see Documents\ComponentOne Samples\WinForms (installed by default) for common-use samples of the custom drop-down functionality. If you need to create a custom control with drop-down functionality, this can be done by deriving a custom control class from C1DropDownControl and overriding its C1DropDownControl.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. In your formatting code, you can use the standard C1Input formatting as a helper or for any other purposes, calling the Format method. Parsing can also be done in event code, in the Parsing event, by setting the 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. 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 various error conditions, such as the errors listed in the following topics.

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

Incorrect format 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 ErrorProvider property (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:

Property Description 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 allows the user to leave the control after error by resetting its value.

ErrorAction Enumerated value that determines what action is performed on the control value when an error occurs. ErrorAction set to None (default) means that the Value is not changed, remains as it was before the unsuccessful value update. If ErrorAction is set to SetValueOnError, control’s Value is set to the value specified in the ValueOnError property of the ErrorInfo class. If ErrorAction is set to ResetValue, control’s Value is set to the last value the control had before it entered edit mode. Setting the ErrorAction property to 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 is set to SetValueOnError.

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

In addition to that, ErrorInfo.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 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 the ShowErrorMessage property to False, or you can change ValueOnError (and set ErrorAction to SetValueOnError), or change the ErrorMessage. 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 ErrorMessage. After the ValidationError event, error handling proceeds as specified in the event’s ErrorInfo argument. If ErrorAction is set to ThrowException, an exception is thrown (using the ErrorMessage text). If BeepOnError is True, the control beeps. If ShowErrorMessage is set to 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 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 and 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). 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 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 set to 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 withDateTimeInput set to 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 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 C1TextBox.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) and Parsing (Updating) Data. However, PostValidation is performed in this case as in all others, see Typed value validation (PostValidation).

Customizing C1Input's Appearance

C1Input is designed to make customization easy for you. You have endless possibilities in changing the default appearance for each C1Input control. C1Input provides numerous property styles for the input boxes, as well as built- in themes for Windows XP and Office 2007.

Visual Styles

C1Input has seven built-in visual styles: System, Office2007Blue, Office2007Black, Office2007Silver, Office2010Blue, Office2010Black, and Office2010Silver. Setting the VisualStyle property on a C1Input control will control the gradients and borders used to paint C1TextBox, C1Label, C1DbNavigator, C1DropDownControl, C1DateEdit (including the drop down calendar), C1NumericEdit (including the drop down calculator), C1SplitButton, C1ComboBox,C1CheckBox, C1RangeSlider and C1Button. To customize the appearance of a C1Input control using Visual Styles, set the VisualStyle property to Custom, Office2007Black, Office2007Blue, Office2007Silver, System, Office2010Blue, Office2010Black, or Office2010Silver. This property can be set either in the designer or in code. The following table describes each of the Visual Styles:

Visual Style Description Custom No visual style (use styles and appearance properties as usual).

Office2007Black Style matches Office2007 Black color scheme.

Office2007Blue Style matches Office2007 Blue color scheme.

Office2007Silver Style matches Office2007 Silver color scheme.

System Style matches the current system settings.

Office2010Blue Style matches Office2010 Blue color scheme.

Office2010Black Style matches Office2010 Black color scheme.

Office2010Silver Style matches Office2010 Silver color scheme.

Using the Designer

Locate the VisualStyle property in the Properties window and set it to Custom, Office2007Black, Office2007Blue, Office2007Silver, System, Office2010Blue, Office2010Black, or Office2010Silver. In this example, the VisualStyle property is set to Office2007Blue for a C1TextBox control.

Using the Code Editor

Add code to the Form_Load event to set the VisualStyle property of a control to Custom, Office2007Black, Office2007Blue, Office2007Silver, or System. The following code sets the VisualStyle property to Office2007Blue for a C1TextBox control: To write code in Visual Basic

Visual Basic Me.C1TextBox1.VisualStyle = C1.Win.C1Input.VisualStyle.Office2007Blue

To write code in C#

C# this.c1TextBox1.VisualStyle = C1.Win.C1Input.VisualStyle.Office2007Blue;

Custom Visual Style

No visual style is applied.

C1TextBox

C1CheckBox

C1Label

C1DbNavigator

C1DropDownControl

C1DateEdit

C1NumericEdit

C1Button

C1ComboBox

C1RangeSlider

C1SplitButton

System Visual Style

The current system settings.

C1TextBox

C1CheckBox

C1Label

C1DbNavigator

C1DropDownControl

C1DateEdit

C1NumericEdit

C1Button

C1ComboBox Note: For illustration purposes two comboboxes are shown.

C1RangeSlider

C1SplitButton

Office2007Black Visual Style

The Office 2007 Black color scheme.

C1TextBox

C1CheckBox

C1Label

C1DbNavigator

C1DropDownControl

C1DateEdit

C1NumericEdit

C1Button

C1ComboBox Note: For illustration purposes two comboboxes are shown.

C1RangeSlider

C1SplitButton

Office2007Blue Visual Style

The Office 2007 Blue color scheme.

C1TextBox

C1CheckBox

C1Label

C1DbNavigator

C1DropDownControl

C1DateEdit

C1NumericEdit

C1Button

C1ComboBox Note: For illustration purposes two comboboxes are shown.

C1RangeSlider

C1SplitButton

Office2007Silver Visual Style

The Office 2007 Silver color scheme.

C1TextBox

C1CheckBox

C1Label

C1DbNavigator

C1DropDownControl

C1DateEdit

C1NumericEdit

C1Button

C1ComboBox Note: For illustration purposes two comboboxes are shown.

C1RangeSlider

C1SplitButton

Office2010Blue Visual Style

The Office 2010 Blue color scheme.

C1TextBox

C1CheckBox

C1Label

C1DbNavigator

C1DropDownControl

C1DateEdit

C1NumericEdit

C1Button

C1ComboBox Note: For illustration purposes two comboboxes are shown.

C1RangeSlider

C1SplitButton

Office2010Black Visual Style

The Office 2010 Black color scheme.

C1TextBox

C1CheckBox

C1Label

C1DbNavigator

C1DropDownControl

C1DateEdit

C1NumericEdit

C1Button

C1ComboBox Note: For illustration purposes two comboboxes are shown.

C1RangeSlider

C1SplitButton

Office2010Silver Visual Style

The Office 2010 Silver color scheme.

C1TextBox

C1CheckBox

C1Label

C1DbNavigator

C1DropDownControl

C1DateEdit

C1NumericEdit

C1Button

C1ComboBox Note: For illustration purposes two comboboxes are shown.

C1RangeSlider

C1SplitButton

Themes

In addition to the Visual Styles you can use the C1ThemeController to apply other themes to the C1Input control. You could also create your own theme using the ThemeDesigner. To customize the appearance of a C1Input control using Themes, add the C1ThemeController to your component tray and set the Themes property to any of the following predefined styles listed below:

Theme Name Image Office2007Black

Office2007Blue

Office2007Silver

Office2010Black

Office2010Blue

Office2010Silver

Office2013DarkGray

Office2013LightGray

Office2013White

ExpressionDark

ExpressionLight

GreenHouse

RainerOrange

ShinyBlue

Violette

VisualStyleOffice2010Black

VisualStyleOffice2010Blue

VisualStyleOffice2010Silver

VS2013Blue

VS2013Dark

VS2013Light

VS2013DarkSolar

VS2013Green

VS2013Purple

VS2013Red

VS2013Tan

How to apply themes to the C1Input controls at Design Time To use the C1ThemeController component with any of the C1Input controls, complete the following:

1. Add any of the C1Input controls, for example C1ComboBox, on the form at design time.

2. Add the C1ThemeController component to your component tray. The C1ThemeController dialog box appears.

If you use the C1ThemeController 2.0 component a C1ThemeController dialog box appears. The ThemeController dialog box is used to quickly to apply the theme to all themeable controls in the application, all themeable controls on the form, or different themes on different controls.

The C1ThemeController dialog box lists all of the components that appears on your form. If you have themeable controls on your form before you add the C1ThemeController the dialog box lists all of the components on your form. Each control/component is initially set to none to prevent unintentional loss of property settings on those controls.

3. In the C1ThemeController dialog box click on the Theme dropdown button next to Form1 and c1ComboBox1 and select one of the predefined themes, for example, Violette.

4. Click OK to save and close the C1ThemeController dialog box. 5. Run your project and observe that the Violette theme is applied to your Form and C1Combobox.

How to Apply Themes to the C1Input Controls Programatically

The following code shows how to programatically apply the built-in theme using the RegisterTheme and SetTheme methods:

To write code in Visual Basic

Visual Basic 'Register the theme file with the C1ThemeController C1.Win.C1Themes.C1ThemeController.RegisterTheme("C:\Users\Documents\Visual Studio 2010\Projects\ThemesProject\ShinyBlue.c1theme") 'Apply it to a control, use the theme name, not the file name Me.c1ThemeController1.SetTheme(c1ComboBox1, "ShinyBlue")

To write code in C#

C# //Register the theme file with the C1ThemeController;

C1.Win.C1Themes.C1ThemeController.RegisterTheme(@"C:\Users\Documents\Visual Studio 2010\Projects\ThemesProject\ShinyBlue.c1theme");

//Apply it to a control and use the theme name this.c1ThemeController1.SetTheme(c1ComboBox1, "ShinyBlue")

In addition to the predefined themes you can customize your theme using the Themes designer. For more information see the Themes for WinForms documentation.

C1Themes and the VisualStyle Property

Many WinForms controls include a property called VisualStyle, of an enum type defined in the control assembly, but following a common naming pattern for the type and possible values. Typically, the enum type is called VisualStyle, with values such as Office2010Blue, Office2010Black, and so on. C1Themes are designed to provide a more powerful and flexible mechanism for adjusting the look of controls. Still there is obvious overlap between the two mechanisms, with the possibility of conflicts. The rules for dealing with this overlap are as follows:

Theme sections for all C1 controls include a VisualStyle property that can be specified by the theme. By default and in all supplied themes, those properties are set to 'Custom' so that the VisualStyle does not interfere with applying other properties. Setting VisualStyle in a theme to anything other than custom sets the corresponding property on the target control and disables applying all other theme properties. (In the C1ThemeDesigner, this actually disables the rest of the theme tree for the control.)

While we recognize that backward compatibility or other considerations may require the use of VisualStyle rather than themes to customize the look of your application, we recommend that if possible you use C1Themes as they provide a more powerful and flexible mechanism for that. Support for visual styles in new controls will be phased out as themes will replace it.

Border Styles

The following border styles are available for C1Input:

Border Preview Style None

FixedSingle

Fixed3D (Default)

Border Color

A border color can be applied to C1DateEdit, C1CheckBox, C1Label, C1NumericEdit, C1DropDownControl, and C1TextBox controls when the border style is set to FixedSingle and the value of the BorderColor property is specified. For more information on applying a border color to an applicable C1Input control see Displaying a Border Color for the C1Input controls.

Cursor Styles

You can customize how the cursor appears when the pointer moves over the control by specifying a value for the Cursor property. You can also customize how the cursor appears when the mouse is over the buttons on the applicable input controls using the ButtonCursor property. The cursor styles are applicable to all C1Input controls. The button cursor styles are applicable to the C1DropDownControl, C1DbNavigator, C1DateEdit, and C1NumericEdit. The cursor and button cursor styles appear like the following:

Button Cursor Style Preview AppStarting

Arrow

Cross

Default

IBeam

SizeAll

SizeNESW

SizeNS

SizeNWSE

SizeWE

UpArrow

WaitCursor

Help

HSplit

VSplit

NoMove2D

NoMoveHoriz

NoMoveVert

PanEast

PanNE

PanNorth

PanNW

PanSE

PanSouth

PanSW

PanWest

Hand

Flat Styles

C1Button provides different flat styles to choose from when you move the mouse over the button control and click it. The ButtonBase.FlatStyle property includes the following values:

Flat Style Preview Standard

Flat

Popup

System

When the ButtonBase.FlatStyle property is set to "Flat" you can modify the border color, border thickness, hover backcolor, and mouse down backcolor using the ButtonBase.FlatAppearance property. The ButtonBase.FlatAppearance property provides the following properties:

BorderColor – Specifies the color of the border around the button. BorderSize – Specifies the size, in pixels, of the border around the button. MouseDownBackColor – Specifies the color of the client area of the button when the mouse is pressed within the bounds of the control. MouseOverBackColor – Specifies the color of the client area of the button when the mouse pointer is within the bounds of the control.

The following image represents a flat style C1Button with its BorderColor, BorderSize, and MouseOverBackColor properties set.

Button Color

In the C1DBNavigator control you can specify whether or not to show blue buttons using the ColorButtons property. You can also specify whether or not to show the colored buttons when hovering over the buttons using the ColorWhenHover property. The following image shows how the colored buttons appear on the C1DBNavigator when the ColorButtons property is set to true.

Input for WinForms Task-Based Help

The task-based help section assumes that you are familiar with programming in the Visual Studio .NET environment, and know how to use C1Input controls in general. If you are a novice to the Input for WinForms product, please see the Input for WinFormsTutorials first. Each topic provides a solution for specific tasks using the Input for WinForms product. By following the steps outlined in each topic, you will be able to create projects using a variety of Input for WinForms features. Each task-based help topic also assumes that you have created a new .NET project.

Adding a Drop-Down Form

To add a drop-down form to your project, complete the following steps:

1. Right-click your project (located in the Solution Explorer) and select Add New Item from the Add sub-menu.

2. In the Add New Item dialog box, select Windows Form from the list of Templates in the right pane. Then enter DropDownForm1.cs in the Name textbox.

3. The next step is to replace the following class definition line(s) in the DropDownForm code:

To write code in Visual Basic

Visual Basic Public Class DropDownForm1 Inherits System.Windows.Forms.Form

To write code in C#

C# Public Class DropDownForm1:System.Windows.Forms.Form

with: To write code in Visual Basic

Visual Basic Public Class DropDownForm1 Inherits C1.Win.C1Input.DropDownForm

To write code in C#

C# Public Class DropDownForm1: C1.Win.C1Input.DropDownForm

The form should look like the image below before editing:

Changing the Navigation in the Navigator

To change the navigation in the Navigator, change Index like the following: To write code in Visual Basic

Visual Basic Private Sub c1DbNavigator1_BeforeAction(sender As Object, e As C1.Win.C1Input.NavigatorBeforeActionEventArgs) If e.Button = C1.Win.C1Input.NavigatorButtonEnum.First Then ' Goto second record instead of the first e.Index = 1 End If

' Go to the last row if user entered too large position If e.Button = C1.Win.C1Input.NavigatorButtonEnum.Position AndAlso e.Cancel Then e.Cancel = False End If End Sub

To write code in C#

C# private void c1DbNavigator1_BeforeAction(object sender, C1.Win.C1Input.NavigatorBeforeActionEventArgs e) { if (e.Button == C1.Win.C1Input.NavigatorButtonEnum.First) {

// Goto second record instead of the first e.Index = 1; }

// Go to the last row if user entered too large position if (e.Button == C1.Win.C1Input.NavigatorButtonEnum.Position && e.Cancel) { e.Cancel = false; } }

Customizing the Drop-Down Editor

The drop-down form below includes option buttons and button controls for the user to make a selection from the C1DropDownControl. The drop-down form appearance properties have been edited so that the form appears as below:

Select the form class name (for this example, WindowsApplication1.DropDownForm1) in the DropDownFormClassName property of your C1DropDownControl. Notice that when you run the project and select the drop-down arrow, the drop-down form now appears.

Enable the button controls on the drop-down form:

1. Set the AcceptButton and CancelButton properties of your DropDownForm1 to button1 and button2, respectively. 2. Select the OK button and set its DialogResult property to OK. Similarly, select the Cancel button and set its DialogResult property to Cancel. 3. To make the drop-down form change the control text when it is closed after the user clicks an item, add the following event handler for the PostChanges event:

To write code in Visual Basic

Visual Basic Private Sub DropDownForm1_PostChanges(sender As Object, e As System.EventArgs) If (MyBase.DialogResult = DialogResult.OK) Then Dim control1 As Control For Each control1 In MyBase.Controls If (TypeOf control1 is RadioButton AndAlso CType(control1, RadioButton).Checked) Then MyBase.OwnerControl.Value = CType(control1, RadioButton).Text End If Next

End If End Sub

To write code in C#

C# private void DropDownForm1_PostChanges(object sender, System.EventArgs e) { if (DialogResult == DialogResult.OK) { foreach (Control control1 in Controls) { if (control1 as RadioButton != null && ((RadioButton)control1).Checked) { OwnerControl.Value = ((RadioButton)control1).Text; } } } } 4. At design time, select DropDownForm1 to view its properties in the Properties window, and then select the Events button from the Properties toolbar. 5. Set the DropDownForm1.PostChanges event to DropDownForm1_PostChanges.

6. To make the OK button (button1) receive focus when the form opens, set the DropDownForm1.FocusControl property to button1. 7. To have a check in the Standard option button, in design time select radiobutton1 and set its Checked property to True.

This topic illustrates the following:

Your form should appear similar to the form below:

Customizing the C1DropDownControl

This topic shows how you can customize the C1Input.C1DropDownControl. To make only the drop-down button visible:

1. Expand the VisibleButtons property node. 2. Set UpDown to False. Note that the DropDown default is set to True. The control should now look like the image below:

To make the width of the drop-down form equal to the width of the control:

1. Select the drop-down form. 2. Set Options.AutoResize to True.

Binding C1CheckBox

The following topics show how to bind C1CheckBox to a Boolean, String, and Integer field.

Binding C1CheckBox to a Boolean Field

To programmatically bind C1CheckBox to a Boolean field, use the following code: To write code in Visual Basic

Visual Basic C1CheckBox1.DataSource = dt C1CheckBox1.DataField = "ColumnBoolean"

To write code in C#

C# C1CheckBox1.DataSource = dt; C1CheckBox1.DataField = "ColumnBoolean";

Binding C1CheckBox to a String Field

To programmatically bind C1CheckBox to a String field, use the following code: To write code in Visual Basic

Visual Basic c1CheckBox1.DataSource = dt c1CheckBox1.DataField = "ColumnString" c1CheckBox1.DataType = GetType(String) ' Use TranslateValues property to translate string values to/from the check box states. c1CheckBox1.TranslateValues.Checked = "Yes" c1CheckBox1.TranslateValues.Unchecked = "No"

To write code in C#

C# c1CheckBox1.DataSource = dt; c1CheckBox1.DataField = "ColumnString"; c1CheckBox1.DataType = typeof(string); // Use TranslateValues property to translate string values to/from the check box states. c1CheckBox1.TranslateValues.Checked = "Yes"; c1CheckBox1.TranslateValues.Unchecked = "No";

Binding C1CheckBox to an Integer Field

To programmatically bind C1CheckBox to an Integer field, use the following code: To write code in Visual Basic

Visual Basic c1CheckBox1.DataSource = dt c1CheckBox1.DataField = "ColumnInt" c1CheckBox1.DataType = GetType(Integer) ‘Use TranslateValues property to translate string values to/from the check box states.

c1CheckBox1.TranslateValues.Checked = 1 c1CheckBox1.TranslateValues.Unchecked = 0

To write code in C#

C# c1CheckBox1.DataSource = dt; c1CheckBox1.DataField = "ColumnInt"; c1CheckBox1.DataType = typeof(int); // Use TranslateValues property to translate string values to/from the check box states. c1CheckBox1.TranslateValues.Checked = 1; c1CheckBox1.TranslateValues.Unchecked = 0;

Setting the Calendar Drop-down

In previous versions of Input for WinForms, the Calendar feature in the C1DateEdit control allowed you to set the "Today" and "Clear" buttons by manipulating the Calendar.UIString property. In newer versions of the C1Input.DateEdit control, you can set these buttons by accessing the C1DateEdit properties menu. To set the "Today" and "Clear" buttons:

1. Add the C1DateEdit control to your form. 2. Select C1.DateEdit1 from the Properties menu. 3. Locate Calendar in the left column and expand the Calendar property.

4. Locate ClearText in the left column and enter "&Reset" in the right column.

5. Locate TodayText in the left column and enter "&Now" in the right column.

6. Press F5 to compile and run the project.

Now when you open the C1DateEdit dropdown menu, the "Today" and "Clear" buttons are set.

Customizing Appearance Using Visual Styles

Setting the VisualStyle property on a C1Input control will control the gradients and borders used to paint C1TextBox, C1Label, C1DbNavigator, C1DropDownControl, C1DateEdit (including the drop down calendar), C1NumericEdit (including the drop down calculator), and C1Button. To customize the appearance of a C1Input control using Visual Styles, set the VisualStyle property to Custom, Office2007Black, Office2007Blue, Office2007Silver, System, Office2010Blue, Office2010Black, or Office2010Silver. This property can be set either in the designer or in code. The following table describes each of the Visual Styles:

Visual Style Description Custom No visual style (use styles and appearance properties as usual).

Office2007Black Style matches Office2007 Black color scheme.

Office2007Blue Style matches Office2007 Blue color scheme.

Office2007Silver Style matches Office2007 Silver color scheme.

System Style matches the current system settings.

Office2010Blue Style matches Office2010 Blue color scheme.

Office2010Black Style matches Office2010 Black color scheme.

Office2010Silver Style matches Office2010 Silver color scheme.

Using the Designer

Using the Code Editor

Add code to the Form_Load event to set the VisualStyle property to Custom, Office2007Black, Office2007Blue, Office2007Silver, or System. The following code sets the VisualStyle property to Office2007Blue for a C1TextBox control: To write code in Visual Basic

Visual Basic Me.C1TextBox1.VisualStyle = C1.Win.C1Input.VisualStyle.Office2007Blue

To write code in C#

C# Me.C1TextBox1.VisualStyle = C1.Win.C1Input.VisualStyle.Office2007Blue

Customizing the C1DateEdit Control

This topic demonstrates how to customize the drop-down of a C1DateEdit control. By default, the drop-down appears like the image below:

Button Visibility

You can hide the Clear and Today buttons by performing the following tasks:

1. Select the C1DateEdit control. 2. In the Properties window, expand the Calendar property node. 3. Set the ShowClearButton and ShowTodayButton properties to False.

Format Display

The FormatType property allows you to edit the date displayed in the box. By default, the date and time are displayed in the box. To only show the date, perform the following task:

1. Select the C1DateEdit control. 2. In the Properties window, set the FormatType property to ShortDate.

Displaying Clicked C1DropDown Buttons in a Text Box

To display clicked C1DropDownControl buttons in a text box, use the C1DropDownControl.UpDownButtonClick event. In this example, the output will be displayed in a textbox (TextBox1). To write code in Visual Basic

Visual Basic Private Sub C1DropDownControl1_UpDownButtonClick(ByVal sender As Object, ByVal e As C1.Win.C1Input.UpDownButtonClickEventArgs) Handles C1DropDownControl1.UpDownButtonClick If (e.Delta = 1) Then Me.TextBox1.AppendText("Up " & ControlChars.CrLf) ElseIf (e.Delta = -1) Then Me.TextBox1.AppendText("Down " & ControlChars.CrLf) End If End Sub

To write code in C#

C# private void c1DropDownControl1_UpDownButtonClick(object sender, C1.Win.C1Input.UpDownButtonClickEventArgs e) { if ((e.Delta == 1)) { this.textBox1.AppendText("Up\r\n"); } else if ((e.Delta == -1)) { this.textBox1.AppendText("Down\r\n"); } }

This topic illustrates the following:

When the Up or Down buttons are clicked in the C1DropDownControl, the words Up or Down will appear in a textbox to indicated which button was pressed.

Working with a Database

The following topics demonstrate how to connect to a database and utilize Input for WinForms features once connected to a database.

Creating a New Connection

To create a new connection, complete the following steps:

1. Select the C1ExpressConnection1.ConnectionString property from the Properties window and select New Connection from the drop-down box. The standard OLE DB Data Link Properties dialog box appears:

2. Select the provider, the database and other necessary connection properties in the dialog box.

In these tutorials, we use the standard MS Access Northwind sample database (C1NWind.mdb).

3. Select Microsoft Jet 4.0 OLE DB Provider in the Provider tab. Once you have chosen the data you can select the Next button.

4. In the Connection tab, click on the ellipsis button to add the C1NWind.mdb database to the ConnectionString. The Select Access Database dialog box will appear. Enter the path, Documents\ComponentOne Samples\Common\C1NWind.mdb (or the location of your database) for the C1NWind.mdb database. Press OK

That will close the Data Link Properties dialog box and put the connection string in the ConnectionString property.

Updating /Refreshing Data from the Database

This topic demonstrates how you can use the Update/Refresh button to send changes and re-fetch data from the database. Complete the following steps:

1. Add a C1DbNavigator control to your form and select the control to view its Properties window. 2. Expand the VisibleButtons property node and set Update and Refresh to True. Set the default navigation buttons (Next, Previous, First, Last) to False. 3. Set the PositionVisible property to False. As an option, you can set its ColorButtons property to True for the buttons to have color bitmaps:

4. To make the Update and Refresh buttons functional, add a Click event handler to the C1DbNavigator component. Enter the following code:

To write code in Visual Basic

Visual Basic

Private Sub c1DbNavigator1_UpdateData(sender As Object, e As System.EventArgs) c1ExpressConnection1.Update() End Sub

Private Sub c1DbNavigator1_RefreshData(sender As Object, e As System.EventArgs) c1ExpressConnection1.Fill() End Sub

To write code in C#

C# private void c1DbNavigator1_UpdateData(object sender, System.EventArgs e) { c1ExpressConnection1.Update(); }

private void c1DbNavigator1_RefreshData(object sender, System.EventArgs e) { c1ExpressConnection1.Fill(); }

Creating a Master-Detail Relation

This topic shows how to create a master-detail relation between tables, C1ExpressTable1 (master) and C1ExpressTable2 (detail).

1. Select the C1ExpressionConnection1 component to view the Properties window. Press the ellipsis button in the Relations property of the C1ExpressionConnection1 control to open the Relations dialog box. 2. In the Relations dialog box, select Products for the Parent field, Order Details for the Child field, and then

select the Add join button to open the Add new join dialog box. 3. Add a join with ProductID for both the Parent field and the Child field. Press OK to close the dialog box.

The join should appear as below:

4. Press OK to close the Relations dialog box.

Customizing the PictureBox

Like most controls, you can easily increase or decrease the size of the C1.Input.PictureBox either using your mouse or through the C1.Input.PictureBox.Size property. But, depending on the dimensions of the picture files, an image might be cut off or might leave a large blank space showing within the PictureBox:

Or…

Perhaps you want your image to appear larger when the program runs. If you increase the size of the PictureBox control you still need to alter the Input.PictureBox.SizeMode for the picture to stretch to the controls boundaries. To Expand the Image in the PictureBox

1. Create .NET project and add the following controls to your form. 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) 2. Arrange the controls to resemble the form below:

3. Enter the following to the C1.Data.Express.C1ExpressTable.ConnectionString property:

"Provider=Microsoft.Jet.OLEDB.4.0;Data Source="Documents\ComponentOne Samples\Common\C1NWind.mdb"

Note: Step 3 assumes that you have the sample file, C1NWind.mdb, in the default location created upon installing the ComponentOne controls. If your database file is in a different location or you want to use a different database file, adjust this entry appropriately.

4. Using the Properties window, bind the remaining controls to the database: Visual Style Description C1DbNavigator1.DataSource C1ExpressTable1

C1Label1.DataSource C1ExpressTable1

C1Label1.DataField LastName

C1Label2.DataSource C1ExpressTable1

C1Label2.DataField FirstName

C1Label3.DataSource C1ExpressTable1

C1Label3.DataField HireDate

C1PictureBox1.DataSource C1ExpressTable1

C1PictureBox1.DataField Photo

C1TextBox1.DataSource C1ExpressTable1

C1TextBox1.DataField Notes

If you ran the program now, the images shown when cycling through the database would not fill the picture box and a large blank space would appear on the form. You need to stretch the image to the boundaries of the PictureBox.

5. Change the C1PictureBox1.SizeMode property from Normal to StretchImage. Notice that there are 3 other options to choose from as well.

6. Run the program and notice how large the employee photo appears.

Navigating the C1DateEdit Control

When end-users select the C1DateEdit control, then press the Enter or Tab to move to another control or select another control with the mouse, the current date is automatically entered into the C1DateEdit control. To move to another control without the date being automatically entered, complete one of the following:

Using the Designer:

1. Create a new .NET project and place a C1DateEdit control and a C1TextBox control on your form. 2. To show end-users that a control has an empty value, in the C1DateEdit.NullText property, enter “{Empty Value}”.

If you ran the program at this point and selected the C1DateEdit control with either the keyboard or mouse, then try to select the C1TextBox control, today’s date would automatically be entered into the C1DateEditr field and you would be unable to leave that field blank.

Notice that the cursor is in the C1TextBox but the current date remains in the C1DateEdit field.

3. Using the Properties window, change the C1DateEdit1.DateTimeInput property to False and change the C1DateEdit1.EmptyAsNull property to True. 4. Run the Program and click on the C1DateEdit control, then click on the C1TextBox.

Notice that even after switching to the C1TextBox, the C1DateEdit field remains empty.

Using the Code Editor:

1. Create a new .NET project and in the Solution Explorer add a reference to the C1Input control. 2. Add the following import statement to the code editor

To write code in Visual Basic

Visual Basic Imports C1.Win.C1Input

To write code in C#

C# using C1.Win.C1Input; 3. Add the C1DateEdit control and C1TextBox control to the Form_Load event.

To write code in Visual Basic

Visual Basic Dim X As New C1DateEdit Controls.Add(X) X.Location = New Point(50, 40) Dim Y As New C1TextBox Controls.Add(Y)

Y.Location = New Point(100, 80)

To write code in C#

C# C1DateEdit X = new C1DateEdit(); Controls.Add(X); X.Location = new Point(50, 40); C1TextBox Y = new C1TextBox(); Controls.Add(Y); Y.Location = new Point(100, 80); 4. To show end-users that the control has an empty value, add the following code to the C1DateEdit entry.

To write code in Visual Basic

Visual Basic X.NullText = "{Empty Value}"

To write code in C#

C# X.NullText = "{Empty Value}";

If you ran the program at this point and selected the C1DateEdit control with either the keyboard or mouse, then try to select the C1TextBox control, today’s date would automatically be entered into the C1DateEdit field and you would be unable to leave that field blank.

5. To preserve the “Empty Value” in the C1DateEdit field even after switching to another control, add the following code to the C1DateEdit entry.

To write code in Visual Basic

Visual Basic X.DateTimeInput = False X.EmptyAsNull = False

To write code in C#

C# X.DateTimeInput = False;

X.EmptyAsNull = False; 6. Run the Program and click on C1DateEdit control, then click on the C1TextBox.

Notice that even after switching to the C1TextBox, the C1DateEdit field remains empty.

Displaying a Border Color for the C1Input Controls

A border color can be applied to C1DateEdit, C1Label, C1NumericEdit, C1DropDownControl, and C1TextBox controls. To create a border color for the C1DropDownControl at design time

1. Add a C1DropDownControl to your form. 2. Navigate to C1DropDownControl’s properties window and set the BorderStyle property to “FixedSingle”. 3. Change C1DropDownControl’s BorderColor property to “Red”.

To create a border color for the C1DropDownControl programmatically

Use the following code to add a border color to the C1DropDownControl: To write code in Visual Basic

Visual Basic Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load Dim dropdown As New C1DropDownControl Me.Controls.Add(dropdown) dropdown.BorderStyle = BorderStyle.FixedSingle dropdown.BorderColor = Color.Red End Sub

To write code in C#

C# private void Form1_Load(object sender, EventArgs e) { C1DropDownControl dropdown = new C1DropDownControl(); this.Controls.Add(dropdown); dropdown.BorderStyle = BorderStyle.FixedSingle; dropdown.BorderColor = Color.Red; }

This topic illustrates the following:

A red border color with a fixed single border style is added to the C1DropDownControl.

Showing a Message Box when the Border Color Changes

You can use the BorderColorChanged event when the value of the BorderColor property changes. To create a message box when the border color changes for C1TextBox, complete the following:

1. Add a C1TextBox control to your form. 2. Navigate to C1TextBox’s properties window and change the BorderStyle property to "FixedSingle". 3. Add a MouseClick event to the C1TextBox control to change C1TextBox’s border color to purple.

To write code in Visual Basic

Visual Basic Private Sub C1TextBox1_MouseClick(ByVal sender As System.Object, ByVal e As System.Windows.Forms.MouseEventArgs) Handles C1TextBox1.MouseClick C1TextBox1.BorderColor = Color.Purple End Sub

To write code in C#

C# private void c1TextBox1_MouseClick(object sender, MouseEventArgs e) {

c1TextBox1.BorderColor = Color.Purple; } 4. Add a BorderColorChanged event to C1TextBox1 to show a message box that informs the user the border color has changed.

To write code in Visual Basic

Visual Basic Private Sub C1TextBox1_BorderColorChanged(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles C1TextBox1.BorderColorChanged MessageBox.Show(“The C1TextBox1 border color change to purple”) End Sub

To write code in C#

C# private void c1TextBox1_BorderColorChanged(object sender, EventArgs e) { MessageBox.Show("The c1TextBox1 border color changed to purple"); }

This topic illustrates the following:

When you mouse click on the C1TextBox control the border color changes to purple. Once it changes to purple the BorderColorChanged event fires and a message box appears informing the user that the border color has changed.

Set IME Mode

The ImeMode property can be used to set an Input Method Editor (IME) mode of the C1Input controls. An Input Method Editor is a program that lets users enter complex symbols or characters, like Japanese Kanji characters, into the input controls, using a basic keyboard. The following table describes the values available for ImeMode property.

Value Description On Indicates that the IME is on. Symbols or characters that are specific to Chinese or Japanese can be entered. Valid for Japanese, Simplified Chinese, and Traditional Chinese IME only.

Off Indicates that the IME is off. The object behaves the same as English entry mode. Valid only for Japanese, Simplified Chinese and Traditional Chinese IME.

Disable Indicates that the IME is disabled. It means that a user cannot turn the IME on from the keyboard as the IME window is hidden.

Hiragana Hiragana Double Byte Characters. Valid only for the Japanese IME.

Katakana Katakana Double Byte Characters. Valid only for the Japanese IME.

KatakanaHalf Katakana Single Byte Characters. Valid only for the Japanese IME.

AlphaFull Alphanumeric Double Byte Characters. Valid only for Korean and Japanese IME.

Alpha Alphanumeric Single Byte Characters. Valid only for Korean and Japanese IME.

HangulFull Hangul Double Byte Characters. Valid only for the Korean IME.

NoControl None (Default).

Inherit Indicated that the IME mode of the parent control is inherited.

Close Indicates that the IME is closed. Valid only for the Chinese IME.

Hangul Hangul Single Byte Characters. Valid only for the Korean IME.

OnHalf Indicates that the IME is on HalfShape. Valid only for the Chinese IME.

Complete the following steps to change the IME mode for the C1Input control:

1. Create a new Windows Application project. Place a C1Input control (C1TextBox, C1ComboBox, C1DateEdit, C1DropDownControl or C1NumericEdit) on the form.

2. From the Properties window, set the ImeMode property, as per your requirement.

Move Focus

This feature makes navigating through the controls easier and allows you to add keyboard navigation support to the C1Input (C1TextBox, C1ComboBox, C1DateEdit, C1DropDownControl and C1NumericEdit) controls. The following properties enable you to move focus from or to the C1Input controls.

ExitOnLastChar: Moves focus from the C1Input control either when the length of the text entered reaches the maximum length, as defined in the MaxLength property, or when the mask is filled. Its default value is False. ExitOnLeftRightKey: Moves focus from the C1Input control when the left or right arrow keys are pressed. Its default value is None. TabStop: Indicates whether the focus is moved to the C1Input control, from the control on the left, when the TAB key is pressed. Its default value is True.

The table below describes values and behavior of the above properties.

Property Possible Value Description ExitOnLastChar True Enables moving focus from the C1Input control when the length of text entered reaches the maximum length, defined in the MaxLength property, or when the mask is filled.

False Disables moving focus from the C1Input control when the length of text entered reaches the maximum length, defined in the MaxLength property, or when the mask is filled.

ExitOnLeftRightKey None Disables moving from the C1Input control when the arrow keys are pressed.

Left Enables moving focus to the control on the left side of the C1Input control, when the left arrow key is pressed.

Right Enables moving focus to the control on the right side of the C1Input control, when the right arrow key is pressed.

Both Enables moving focus to the control on either left or right side of the C1Input control, when the respective key is pressed.

TabStop True Enables moving focus to the C1Input control, from the control on the left side of the C1Input control, when the TAB key is pressed.

False Disables moving focus to the C1Input control, from the control on the left side of the C1Input control, when the TAB key is pressed.

Complete the following steps to enable or disable this feature in the C1Input control:

1. Create a new Windows Application project. Place a C1Input control (C1TextBox, C1ComboBox, C1DateEdit, C1DropDownControl or C1NumericEdit) on the form.

2. From the Properties window, set either one or all of the following properties, as per your requirement. Set the ExitOnLastChar to true or false, to enable or disable moving focus from the control when the text entered reaches the maximum length. Set the ExitOnLeftRightKey to Left, Right or Both, to enable moving the focus from the control when the respective key is pressed. Set the TabStop to true or false, to enable or disable moving focus to the C1Input control, when the tab key is pressed.

Select Specific Calendar Type

The CalendarType property, present in the C1DateEdit and C1NumericEdit controls lets you select specific calendar types to use a non-default Calendar. The following calendar types are supported by C1DateEdit and C1NumericEdit controls:

Default ChineseLuniSolarCalendar EastAsianLunisolarCalendar GregorianCalendar HebrewCalendar HijriCalendar JapaneseCalendar JapaneseLunisolarCalendar JulianCalendar KoreanCalendar KoreanLunisolarCalendar TaiwanCalendar TaiwanLunisolarCalendar ThaiBuddhistCalendar UmAlQuraCalendar

Complete the following steps to change the calendar type for the C1Input control:

1. Create a new Windows Application project. Place a C1Input control (C1DateEdit or C1NumericEdit) on the form. 2. From the Properties window, set the CalendarType property, as per your requirement.

Spin Up/Spin Down Programmatically

The SpinUp and SpinDown methods enable you to increase or decrease the values entered in the C1Input controls (C1ComboBox, C1DropDownControl, C1DateEdit and C1NumericInput) when the focus is not on the control. In addition to the above methods, C1ComboBox and C1DateEdit contain an additional property AllowSpinLoop that, when set to true, loops through the items when the SpinUp or SpinDown method is invoked. Following is an example to use the SpinUp method:

1. Create a new Windows Application project. Place a C1NumericEdit control on the form. 2. From the Properties window, set the Value property to 0. 3. Add a textbox control onto the form and double click the textbox to generate the TextChanged event, in code. 4. Add the following code to the textbox's TextChanged event.

To write code in Visual Basic

Visual Basic Private Sub TextBox1_TextChanged(sender As Object, e As EventArgs) Handles

TextBox1.TextChanged c1NumericEdit1.SpinUp(1) End Sub

To write code in C#

C# private void textBox1_TextChanged(object sender, EventArgs e) { c1NumericEdit1.SpinUp(1); } 5. Run the project.

What You've Accomplished

When you enter characters into the textbox control, the value in the C1NumericEdit control will increase by 1, each time a new character is entered, giving you the count of characters entered in the control.

Change Up-Down Button Alignment

The UpDownButtonAlignment property lets you change the alignment of the Up and Down buttons present next to the DropDown button in C1DropDown, C1DateEdit and C1NumericEdit. This property can have the following values:

Default: Both the buttons are placed on the right side, along with the drop-down button.

UpLeftDownRight: The Up button is placed on the left side and the Down button is placed on the right side.

UpRightDownLeft: The Up button is placed on the right side and the Down button is placed on the left side.

Complete the following steps to change the alignment of the Up and Down buttons:

1. Create a new Windows Application project. Place a C1Input control (C1DropDown, C1DateEdit or C1NumericEdit) on the form. 2. From the Properties window, set the UpDownButtonAlignment property, as per your requirement.

Input for WinForms Samples

Please be advised that this ComponentOne software tool is accompanied by various sample projects and/or demos which may make use of other development tools included with the ComponentOne Studio. Please refer to the pre-installed product samples through the following path: Documents\ComponentOne Samples\WinForms

Note: The Samples are also available at http://helpcentral.componentone.com/Samples.aspx.

Visual basic samples

The following Visual Basic samples are included with C1Input:

Sample Description CreditCardDropDown Using a custom drop-down 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 drop-down portion to change font properties in a more convenient way. This sample uses the C1DropDownControl, C1TextBox, and DropDownForm controls.

LookUpSample Shows how to create a custom drop-down control with names from a lookup table. The UpDown button scrolls the names, while the ellipsis (...) button allows to enter a new name.

NumPadDropDown1 Replaces the standard calculator in a C1NumericEdit control with the custom drop-down 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.

ComboBoxFeatures Demonstrates the basic features of C1ComboBox such as the difference between the Default and DropDownList styles, how to bind the dropdownlist to an enum, array of strings, and a bindingsource, and how to control the drop down form size using the MinimumSize and MaximumSize properties.

ComboBoxImages Shows how to easily use images from the ImageList in the dropdown items of the C1ComboBox control.

ComboBoxItemModes Demonstrates how to use the different values (Default, HtmlPattern, and Html) from the ItemMode property.

SplitButtons This sample shows how to use the C1SplitButton control.

SplitButtonsBasic This sample shows how to use the basic features of the C1SplitButton control such as how to use the Save and SaveAs actions.

C# samples

The following C# samples are included with C1Input: