Format Property (TDBDate)

The format is specified by creating a mask using keywords and literals. Note that the input mask must not exist only with literals.

Syntax

TDBDate.Format= string

Read/Write at run time and design time.

Values

The following are the keywords available in the Format property (yyyy/mm/dd is the default):

y, yy	Display the year as a 2-digit number (00 - 99).
yyy, yyyy	Display the year as a 4-digit number (0100 - 9999).
m, mm	Display the month as a number with a leading zero (01 - 12).
mmm	Display the month as an abbreviation (Jan - Dec).
MMM	Display the month as an abbreviation (JAN - DEC).
d, dd	Display the day as a number with a leading zero (01 - 31).
g	Display the era name in alphabet (M, T, S, H).
gg	Display the first character (DBCS) era.
ggg	Display the full (DBCS) era.
e	Display the nengo year as a single digit number when possible.
ee	Display the nengo year as a 2 digit number.
{}	Specify a zero-length string or a SBCS character between the braces which fills the character in all the digits of the input mask for Null and era format patterns.
;	Delimiter between different format patterns.

Remarks

When using the mmm or MMM keywords, the user will only need to key enough characters to uniquely identify the month. For example, typing "F" would complete the field with Feb, whereas typing "AP" would be needed to differentiate between April and August. These abbreviation months can also be keyed with numbers. For example, typing "2" or "02" would complete the field with Feb, whereas typing "1" would be needed to differentiate between October-"10", November-"11" and December-"12". Note that January must be entered by typing "01" to complete the field.

The Era name fields defined using the g, gg or ggg keywords can also be keyed using the initial character (M, T, S, H) or a numeric value (0, 1, 2, 3) that uniquely identifies the Era name. This will become very useful when users enter era values though the ten keys.

When keywords need to be used as literals, place a backslash before the keyword. This will differentiate a keyword from a literal.

TDBDate.Format = "Date: yyyy.mmm.dd"

TDBDate.Value = CDate("1998/3/16")

Debug.Print TDBDate.Text

With this code, a text string: "Date: 1998.Mar.16 " will be printed out in the Debug window.

When including single keywords such as "y", "m", "d" or "e" in the format, the control treats them equivalently as "yy", "mm", "dd", "ee".

The Format property now provides a new free format entry. This is available only when a zero-length string (") is set to the Format. This feature allows the user to type in any string expressions that can be converted to a date value. The control accepts any entered or passed in invalid characters (the InvalidInput event will not be fired). When the focus moves out of the control, the entered string will be converted into a date value using the format specified in the DisplayFormat property. If the DisplayFormat property is set to a zero-length string, the display text of the entered date will not change. If the string expression could not be converted, the InvalidValue event will be fired, notifying the user that the entered string was an invalid value. If the converted valid value was out of the MaxDate and the MinDate range, the InvalidRange event will be fired.

The following code demonstrates how the free format entry is handled:

TDBDate.Format = ""

TDBDate.DisplayFormat = "g. ee.mm.dd"

With the example above, if enter a date "1998-01-01", and move the focus away from the control, the date value will be automatically converted, and will display "H. 10.01.01".

Now, if you set both the Format and the DisplayFormat to a zero-length string such as:

TDBDate.Format = ""

TDBDate.DisplayFormat = ""

The entered date "1998 01 01" will be converted to a date value, and kept displayed "1998 01 01".

This feature is very effective when working with dates without getting bound to a specific format, which gives more flexibility to the end user for enhanced data entry.

When the control allows free format entry, the following properties will not take any effect.

Please refer to the individual properties for further details: Spin Object, CurrentField, PromptChar, ShowLiterals.

The Format property also allows you to determine three separate format patterns, delimited with a semicolon (";"). The first pattern is used to define the input mask, the second for Null values and the third for values that cannot be expressed in era format. For example:

TDBDate.Format = _

"yyyy/mm/dd;Null;Can't be expressed in Era format"

You can also simplify the Null and the Era format patterns by using braces ("{}") to specify a SBCS character to fill in all digits based on the input mask. For example, string expressions such as "9999/99/99"can be set as:

TDBDate.Format = "yyyy/mm/dd;{9};{9}"

The era expression can be used in the following situation:

TDBDate.Format = "ggg. ee/mm/dd;;{9}"

TDBDate.Value = "1500/01/01"

With this example, the control will display a string, "9999 99/99/99" since 1500/01/01 can not be expressed in the Era format. Once you start inputting, the input mask will be applied.

If a zero-length string is set between the braces such as "yyyy/mm/dd;{};{}", the control will display blank when setting the value to Null or Era.

When more than one character is defined within the braces, the control picks the first character in the expression for implementing.

Note that the keywords except the braces ("{}") will be treated as literal characters within the Null and the Era patterns. If the braces are needed, place a backslash before them to differentiate from a literal.

If the Null expression and the era expression is omitted, the control uses the default input mask which includes all the literals and the prompt character specified in the PromptChar property (default is "_") to express Null and Era (same as when clearing the control). However, if the control allows free format entry, a zero-length string will be displayed.

When Format and DisplayFormat are both set to a zero-length string, the value set by code and the date selected from the Calendar will be displayed using the system short date. For example:

TDBDate.Format = ""

TDBDate.DisplayFormat = ""

TDBDate.Value = "03/16/98"

In the case above, the control can not determine in what format to display the current underlying value. Therefore, the system short date will be applied and the control will display as "1998/03/16".

The Null and the Era format patterns will be ignored when the input mask is not defined. For example, a format string such as ";{9};{0}" or ";Null;Can't Express" will be treated equivalent as " - a zero-length string. This is because in free format entry, the control cannot distinguish between the entered text and the text defined as the Null and Era patterns. The following shows the relation between the Format and the DisplayFormat property.

If the DisplayFormat property is set to a zero-length string, the format string set to the Format property will be used both for inputting and displaying.

TDBDate.Format = "yyyy.mm.dd;Null;Era"

TDBDate.DisplayFormat = ""

If the mask section of the DisplayFormat property is omitted, only the input mask defined in the Format property will be inherited. Note that the Null and the Era patterns will not be overridden.

TDBDate.Format = "yyyy.mm.dd"

TDBDate.DisplayFormat = ";Null;Era"

TDBDate.Format = ""

TDBDate.DisplayFormat = ";Null;Era"

The following example will be treated equivalent to setting both the Format and the DisplayFormat properties to a zero-length string. This is because the control can not determine which input mask to base on for filling in a SBCS character in all the specified digits.

TDBDate.Format = ""

TDBDate.DisplayFormat = ";{9};{9}"

If the mask section of both the Format and the DisplayFormat property are defined, the input mask and the display mask will work independent, without inheriting or influencing each other.

TDBDate.Format = "yyyy.mm.dd;Null;Era"

TDBDate.DisplayFormat = "dd.mm.yyy"

When setting the input mask to 'yyyy/mm' with the underlying value set to "1998/01/31", by clearing the contents of the control will cause the Value to be set to Null and the Day property to -1. If once input data such as "1998/05", the Value will be set to "1998/05/31" and the Day property set back to 31. If a data such as "1998/02" is inputted, the Value will be automatically rounded to "1998/02/28" and the Day property to 28. If the underlying date is set to Null, entering data such as "1998/05" will return 1998/05/01, picking up the smallest day (value) within the month. The Day property will return a 1 in this case.

The character specified between the braces ("{}") in the input mask must be set to a zero-length string or a SBCS character. A DBCS character will be treated as an error.

The input mask is recommended to use the four digit years "yyyy" instead of two. This is to avoid the year 2000 (Y2K) compliant problems.