DisplayFormat Property (TDBTime)

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

Returns and sets the display format used in the control.

Syntax

TDBTime.DisplayFormat= string

Read/Write at run time and design time.

Values

The following are the keywords available in the DisplayFormat property:

h	Display the hour as a number without leading zeros (0 - 23).
hh	Display the hour as a number with leading zeros (00 - 23).
n	Display the minute as a number without leading zeros (0 - 59).
nn	Display the minute as a number with leading zeros (00 - 59).
s	Display the second as a number without leading zeros (0 - 59).
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 display mask for the Null format pattern.
;	Delimiter between different format patterns.

Remarks

The format is specified by creating a mask using keywords and literals. If this property is set to a zero-length string, the Format property setting will be used for the display format.

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

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

TDBTime.Value = "15:00:00"

Debug.Print TDBTime.DisplayText

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

You can use this property to separate the display format from the input format, making it possible to display times in complex formats but with easy input.

For example, to display 11:00:00 AM, and yet have the user key only 110000, set DisplayFormat property to hh:nn:ss AM/PM and the Format property to hh:nn:ss. Combining the use of DisplayFormat with Format reduces keystrokes.

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

TDBTime.DisplayFormat = "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 display mask. For example, string expressions such as "99:99:99 99" can be set as:

TDBTime.DisplayFormat = "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.

The DisplayFormat property features the DisplayText property to return 24:00:00 as the midnight expression when the display format is set to a 24-hour format ("hh:nn:ss") and the MidnightMode property is set to 1-Midnight As 24 o'clock. For example:

TDBTime.DisplayFormat = "hh:nn:ss"

TDBTime.Value = "00:00:00"

TDBTime.MidnightMode = dbiMidnightAs24

Debug.Print "DisplayText: " & TDBTime.DisplayText

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

DisplayText: 24:00:00

The "24:00:00" midnight expression is available displaying only when moving the focus away from the control, and can not be used within the input mask when entering data.

You can also return or set to determine the range for the 12-hour mode, either to 00:00:00 - 11:59:59, or 01:00:00 - 12:59:59, by setting the Hour12Mode property. This can effect the Hour, Text and the DisplayText properties when either the Format or the DisplayFormat property 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

With the example above, the following text strings 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

With the example above, the following text strings will be printed out to the Debug window.

Hour: 12

Text: 12:00:00

DisplayText: 00:00:00 PM

If the Null expression is omitted, the control uses the display format, 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).

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 equivalent as to a zero-length string.

When DisplayFormat and Format 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 AM"

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

The following shows the relation between the DisplayFormat and the Format 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 the same as setting both the Format and the DisplayFormat properties to a zero-length string. This is because the control cannot 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"

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