A C# Numeric Field Control
An abstract base for a numeric fielded control.
- Download demo project [VS 05] - 54.4 KB
- Download source [VS 05] - 31.2 KB
- Download demo project [VS 08] - 54.5 KB
- Download source [VS 08] - 31.6 KB

Introduction
After creating an IP address control for the .NET Framework, I applied the lessons learned towards creating an abstract control. This control can be easily configured to allow input of any value that is a collection of numeric fields, such as an IP address, IP address with ports, IPv6 address, MAC address, telephone number, or Social Security Number.
Background
FlexFieldControl
is an abstract UserControl
-based class that aggregates n controls of type FieldControl
and n+1 controls of type SeparatorControl
. These controls are arranged horizontally in an alternating fashion, beginning with a SeparatorControl
. Below is an image of a default FlexFieldControl
-based control, with the aggregated controls highlighted:

By default, FlexFieldControl
has three FieldControl
s and four SeparatorControl
s. Following the API below is an example of how to extend FlexFieldControl
to create a new control, MACAddressControl
, with just eleven lines of code.
Using the Code
Once the library containing FlexFieldControl
(FlexFieldControlLib.dll) is built, add the DLL as a reference to your Windows Forms project. FlexFieldControl
is defined as abstract
; it will not appear in the Toolbox of the Windows Forms designer. However, any control based on FlexFieldControl
will.
Public Instance Properties
AutoHeight
- Gets or sets a value indicating whether the control is automatically sized vertically according to the current font and border. The default value istrue
Blank
- Gets a value indicating whether all of the fields in the control are emptyBorderStyle
- Gets or sets the border style of the control. The default value isBorderStyle.Fixed3D
FieldCount
- Gets or sets the number of fields in the control. The default value is3
and the minimum value is1
. Setting this value resets every field and separator to its default stateReadOnly
- Gets or sets a value indicating whether the contents of the control can be changedText
- Gets or sets the text of the control
Public Instance Methods
AddCedeFocusKey
- Adds a specific keystroke to a field that cedes focus to the next field in the control. By default, the [Space] key will cede focus for any field that is not blankClear
- Clears all text from all fields in the controlClearCedeFocusKeys
- Removes all keystrokes that cede focus from a fieldGetCasing
- Gets the character casing for a field in the control. The default isCharacterCasing.Normal
GetFieldText
- Gets the text for a field in the controlGetLeadingZeros
- Gets whether a field that is not blank has leading zeros. The default value isfalse
GetMaxLength
- Gets the maximum number of characters allowed for a field. The default value is3
GetRangeHigh
- Gets the maximum value allowed for a field. The default value is based on the maximum length and value format of the fieldGetRangeLow
- Gets the minimum value allowed for a field. The default value is0
GetSeparatorText
- Gets the text for a separator in the controlGetValue
- Gets the value for a field in the control. If the field is blank, its value is the same as its low range valueGetValueFormat
- Gets the value format for a field in the control. The default isValueFormat.Decimal
HasFocus
- Gets whether a field in the control has input focusIsBlank
- Gets whether a field in the control is blankResetCedeFocusKeys
- Resets a field to its default cede focus key, the [Space] keySetCasing
- Sets the character casing for a field in the controlCharacterCasing.Lower
will minimize the horizontal size for a field that has a value format ofValueFormat.Hexadecimal
SetFieldText
- Sets the text for a field in the controlSetFocus
- Sets input focus to a field in the controlSetLeadingZeros
- Sets whether a field that is not blank has leading zerosSetMaxLength
- Sets the maximum number of characters allowed for a field. The minimum value is1
; the maximum value depends on the value format:9
characters for decimal values and7
characters for hexadecimal valuesSetRange
- Sets the minimum and maximum values allowed for a field in the controlSetSeparatorText
- Sets the text for a separator in the controlSetValue
- Sets the value for a field in the controlSetValueFormat
- Sets the value format for a field in the controlToString
- Gets the text of the control. If any field is blank, that field's text will be its low range value
The client code can register a handler for the public event, FieldChangedEvent
, to be notified when the text in any field of the control changes. Another public event, FieldValidatedEvent
, notifies when the text of any field is validated. Note that Text
and ToString()
may not return the same value. If there are any empty fields in the control, Text
will return a value that will reflect the empty fields. ToString()
will fill in any empty fields with that field's low range value.
Creating MACAddressControl
Here is the source code for creating a simple MACAddressControl
:
using System;
using System.Windows.Forms;
using FlexFieldControlLib;
namespace TestFlexFieldControl
{
class MACAddressControl : FlexFieldControl
{
public MACAddressControl()
{
// the format of this control is 'FF:FF:FF:FF:FF:FF'
// set FieldCount first
//
FieldCount = 6;
// every field is 2 digits max
//
SetMaxLength( 2 );
// every separator is ':'...
//
SetSeparatorText( ":" );
// except for the first and last separators
//
SetSeparatorText( 0, String.Empty );
SetSeparatorText( FieldCount, String.Empty );
// the value format is hexadecimal
//
SetValueFormat( ValueFormat.Hexadecimal );
// use leading zeros for every field
//
SetLeadingZeros( true );
// use uppercase only
//
SetCasing( CharacterCasing.Upper );
// add ':' key to cede focus for every field
//
KeyEventArgs e = new KeyEventArgs( Keys.OemSemicolon );
AddCedeFocusKey( e );
// this should be the last thing
//
Size = MinimumSize;
}
}
}
The first step in the constructor should always be setting the FieldCount
for the control. Otherwise, any prior settings will be reset. For instance, if the value format of every field was set to ValueFormat.Hexadecimal
and then FieldCount
was changed, the value format of each field would be reset to its default, ValueFormat.Decimal
.
The next step is to set the maximum number of characters allowed in each field. In this case, every field is set to the same maximum length via SetMaxLength( 2 )
. Alternatively, each field could be set individually: SetMaxLength( 0, 2 )
, SetMaxLength( 1, 2 )
, SetMaxLength( 2, 2 )
, etc. The first parameter in SetMaxLength
is the zero-based index of a field in the control.
By default, each separator has the text "<", "><", or ">" depending on its location within the control. For this MACAddressControl
, each separator except for the first and last has ":" as its text. SetSeparatorText( ":" )
sets the text of every separator to ":". To clear the text of the first and last separators, SetSeparatorText( 0, String.Empty )
and SetSeparatorText( FieldCount, String.Empty )
are called.
The default value format of each field is ValueFormat.Decimal
, but this control uses hexadecimal values in each field. Calling SetValueFormat( ValueFormat.Hexadecimal )
sets every field in the control to a hexadecimal value format. Alternatively, SetValueFormat
can be called with a field index to set the value format of an individual field.
Since MAC addresses are commonly displayed with leading zeros in each field -- i.e., "08:09:0A:0B:0C:0D" rather than "8:9:A:B:C:D" -- each field is set to show leading zeros with the call SetLeadingZeros( true )
. Alternatively, SetLeadingZeros
can be called with a field index to set the leading zeros property of an individual field. By default, each field does not display leading zeros.
This control forces hexadecimal letters in every field to be displayed as capitals by calling SetCasing( CharacterCasing.Upper )
. If a user enters "a" in any field, the control will display "A" in that field. Alternatively, SetCasing
can be called with a field index to set the character casing of each field individually. As a convenience to the user, this control adds the [;] key as a cede focus key to each field, using:
KeyEventArgs e = new KeyEventArgs( Keys.OemSemicolon );
AddCedeFocusKey( e );
If the value of a field can be represented by one character, the user can enter that character and then press the [;] key or the [Space] key to advance the input focus of the control to the next field. Alternatively, AddCedeFocusKey
can be called with a field index to set the cede focus keys for each field individually.
The final call in the constructor, Size = MinimumSize
, forces the control to be as small as possible. As settings change, the control will only grow to accommodate them; it will not automatically shrink. Once the control is placed on a form, it can be resized as necessary.
History
- 29 April 2008
- Added propagation for
PreviewKeyDown
,KeyDown
, andKeyUp
events
- Added propagation for
- 20 November 2007
- Added
Dispose()
calls when recreating subcontrols onFieldCount
change. Thanks to Glenn for reporting this problem
- Added
- 23 October 2007
ReadOnly
should now really be read-only
- 4 October 2007
- Added proper event propagation for some mouse events
- Added the
AnyBlank
property - Removed superfluous code
- Addressed a potential resource leak when calculating text size
- Compliant with FxCop 1.35
- 23 July 2007
- Fixed bug related to setting text of fields with leading zeros. Thanks once again to zeno_nz for reporting this problem
- 15 July 2007
GotFocus
andLostFocus
events are consistently raised- The
AllowInternalTab
property was added to allow tabbing within the control. The default value isfalse
- 27 June 2007
- Changes to
Text
property are persisted in design mode - The
KeyPress
event can be trapped by clients of the library. Thanks to zeno_nz for requesting this enhancement
- Changes to
- 5 June 2007
- Initial release