Format Property (TDBTime)

Reference> TDBTime Control> TDBTime Control Properties> Format Property (TDBTime)

The Format property is specified by creating a mask using keywords and literals.

Syntax

TDBTime.Format= string

Read/Write at run time and design time.

Values

The following are the keywords available in the Format property (hh:nn:ss is the default):

h, hh	Display the hour as a number with leading zeros (00 - 23).
n, nn	Display the minute as a number with leading zeros (00 - 59).
s, ss	Display the second as a number with leading zeros (00 - 59).
AM/PM	Use the 12-hour mode and display an uppercase AM with any hour before noon; display an uppercase PM with any hour between noon and 11:59 P.M.
am/pm	Use the 12-hour mode and display a lowercase AM with any hour before noon; display a lowercase PM with any hour between noon and 11:59 P.M.
A/P	Use the 12-hour mode and display an uppercase A with any hour before noon; display an uppercase P with any hour between noon and 11:59 P.M.
a/p	Use the 12-hour mode and display a lowercase A with any hour before noon; display a lowercase P with any hour between noon and 11:59 P.M.
AMPM	Use the 12-hour mode and display the AM string literal as defined by your system with any hour before noon; display the PM string literal as defined by your system with any hour between noon and 11:59 P.M. AMPM can be either uppercase or lowercase, but the case of the string displayed matches the string as defined by your system settings.
{}	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 the Null format pattern.
;	Delimiter between different format patterns.

Remarks

Note that the input mask must not exist only with literals.

When using the AM/PM, am/pm, A/P, a/p, AMPM keywords, the user will only need to keyed the initial character (A, P) or a numeric value (0, 1) that uniquely identifies the 12-hour mode. 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.

TDBTime.Value = CDate("15:00:00")

TDBTime.Format = "Time Format: hh:nn:ss AM/PM"

Debug.Print TDBTime.Text

In this example, a text string: "Time Format: 03:00:00 PM" will be printed out in the Debug window.

You can use the Hour12Mode property to determine the range for users entering time values when the Format property is set to a 12-hour format ("hh:nn:ss"): either the range of 00:00:00 - 11:59:59, or 01:00:00 - 12:59:59. This can affect the Hour, Text and the DisplayText properties when either the Format or the DisplayFormat is set to a 12-hour format ("hh:nn:ss"). For example:

TDBTime.Format = "hh:nn:ss AM/PM"

TDBTime.DisplayFormat = ""

TDBTime.Value = "00:00:00"

TDBTime.Hour12Mode = dbiHour0As12

Debug.Print "Hour: " & TDBTime.Hour

Debug.Print "Text: " & TDBTime.Text

Debug.Print "DisplayText: " & TDBTime. DisplayText

In the example above, the following text string will be printed out to the Debug window.

Hour: 12

Text: 12:00:00 AM

DisplayText: 12:00:00 AM

Consider another example:

TDBTime.Format = "hh:nn:ss"

TDBTime.DisplayFormat = "hh:nn:ss AM/PM"

TDBTime.Value = "12:00:00"

TDBTime.Hour12Mode = dbiHour12As0

Debug.Print "Hour: " & TDBTime.Hour

Debug.Print "Text: " & TDBTime.Text

Debug.Print "DisplayText: " & TDBTime. DisplayText

In the example above, the following text string will be printed out to the Debug window.

Hour: 12

Text: 12:00:00

DisplayText: 00:00:00 PM

When including single keywords such as "h", "n", "s" in the format, the control treats them as equivalent to "hh", "nn", "ss".

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 time value. The control accepts any typed 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 time 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 MaxTime and the MinTime range, the InvalidRange event will be fired.

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

TDBTime.Format = ""

TDBTime.DisplayFormat = "hh:nn:ss AM/PM"

In the example above, if you enter the time "15.30.30", and move the focus away from the control, the time value will be automatically converted, and will display "03:30:30 PM".

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

TDBTime.Format = ""

TDBTime.DisplayFormat = ""

The entered time "13 50 50" will be converted to a time value, and kept displayed "13 50 50".

This feature is very effective when working with times without getting bound to a specific format, where 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 these properties for further details: Spin, CurrentField, PromptChar, ShowLiterals.

The Format property also allows you to determine two separate format patterns, delimited with a semicolon (";"). The first pattern is used to define the input mask and the second for expressing Null values. For example:

TDBTime.Format = "hh:nn:ss AM/PM;Null"

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

TDBTime.Format = "hh:nn:ss AM/PM;{9}"

If a zero-length string is set between the braces such as "hh:nn:ss AM/PM;{}", the control will display blank when setting the value to Null.

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 pattern. If the braces are needed, place a backslash before them to differentiate from a literal.

If the Null 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 (same as when clearing the control). However, if the control allows free format entry, a zero-length string will be displayed.

When the Format and DisplayFormat properties are both set to a zero-length string, the value set by code will be displayed using the system format. For example:

TDBTime.Format = ""

TDBTime.DisplayFormat = ""

TDBTime.Value = "01:00:00 PM"

In the case above, the control cannot determine in which format to display the current underlying value. Therefore, the system format will be applied and the control will display "13:00:00".

The Null format pattern will be ignored when the display mask is not defined. For example, a format string such as ";{9}" or ";Null" will be treated as equivalent to"- 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 pattern.

The following shows the relation between the Format and DisplayFormat properties.

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.

TDBTime.Format = "hh:nn:ss AMPM;Null"

TDBTime.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 pattern will not be overridden.

TDBTime.Format = "hh:nn:ss"

TDBTime.DisplayFormat = ";Null"

TDBTime.Format = ""

TDBTime.DisplayFormat = ";Null"

The following example will be treated as 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.

TDBTime.Format = ""

TDBTime.DisplayFormat = ";{9}"

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

TDBTime.Format = "hh:nn:ss;Null"

TDBTime.DisplayFormat = "hh:nn:ss AMPM"

When setting the input mask to 'hh:nn' with the underlying value set to "13:30:30", and by clearing the contents of the control, you will cause the Value to be set to Null and the Second property to -1. If once input data such as "15:50", the Value will be set to "15:50:30" and the Second property set back to 30. If the underlying time value is set to Null, entering data such as "09:15" will return 09:15:00, picking up the smallest second (value). The Second property will return a 0 in this case.

Unlike Visual Basic, the m keyword will be treated as a literal, although immediately following h or hh.

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