DisplayFormat Property (TDBNumber)

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

Sets/returns the display format used in the control.

Syntax

control.DisplayFormat= string

Read/Write at run time and design time.

Values

The following are the keywords available in the DisplayFormat property (####0;;;Null is the default):

#	Defines an optional numeric character.
0	Defines a required numeric character.
.	A period that defines the location of the decimal point.
,	A comma that defines the location of the separator.
;	Delimiter between different format patterns.
{}	Specify a zero-length string or SBCS character between the braces which fills the character in all the digits of the display mask for the Zero and the Null format patterns.

Remarks

The display format string is specified by creating a mask using keywords and literals. The literals cannot be specified between the keywords, but must be set on both ends of the mask, as in "Plus ###.## $". When keywords need to be used as literals, place a backslash before the keyword. This will differentiate a keyword from a literal.

If this property is set to a zero-length string, the format string set in the Format property will be applied to both when inputting and displaying. The number of digits set in this property must not exceed the maximum of fifteen digits.

The format string is made up of four separate format patterns, delimited with a semicolon (";"). The first pattern is used for positive values, the second for negative values, the third for zero values and the fourth for Null values. For example:

TDBNumber.DisplayFormat = _

"Plus ###.##;Minus ###.##;Zero;Null"

You can simplify the Zero and the Null format patterns by using braces ("{}") to specify a SBCS character to fill in all number digits based on the display mask. For example, string expressions such as " #####.## $" can be set as:

TDBNumber.DisplayFormat = "#####.## $;;{#};{#}"

If more than one character is defined within the braces, the control picks the first character in the expression for implementing. If a zero-length string is set between the braces such as "$###,##.##;;{};{}", the control will display blank when setting the value to Zero or Null.

Positive Pattern:

The first pattern may be omitted. If this pattern is not specified, the positive format used in the Format property will be inherited. For example:

TDBNumber.Format = "#.###"

TDBNumber.DisplayFormat = ""

If both the input and display format is set to a zero-length string, 15 number of digits - "###############" will be automatically set as the default format.

The following shows all the possible patterns available with the display format using the keywords:

#,#

#,0

0,0

#.#

#.0

0.#

0.0

It is important to note that the decimal point must be present in the pattern if the number contains decimal digits. The number will be rounded down if a sufficient number of decimal digits are not specified.

You can display the leading zero or fill the decimal places with place-holding zeros by setting the input format such as:

' Display the leading zero

TDBNumber.DisplayFormat = "0.###"

' Fill the decimal digits with place-holding zeros

TDBNumber.DisplayFormat = "#.000"

Negative Pattern:

The second pattern may also be omitted. If this pattern is not specified, the first (positive) pattern will be used for the negative numbers with a minus sign added. The following examples show how the format string would affect the display of the number when the Value property is 1234 or negative 1234:

TDBNumber.DisplayFormat = "$#####.##"

' Positive: "$1234"

' Negative: "-$1234"

Since the second pattern was not specified, the default was used adding the minus sign to the first pattern.

TDBNumber.DisplayFormat = "####0.00;(####0.00)"

' Positive: "1234.00"

' Negative: "(1234.00)"

TDBNumber.DisplayFormat = "####0.00;####0.00"

' Positive: "1234.00"

' Negative: "1234.00"

Since the second pattern does not specify any indicator for a negative value, the only indication to the user will be the color of the text, as defined in the NegativeColor property.

TDBNumber.DisplayFormat = "00000"

' Positive: "01234"

' Negative: "-01234"

Since the pattern uses "0" rather than "#", the number will be displayed with leading zeros.

The number of numeric digits specified in the second pattern must be exactly the same as in the first pattern.

Zero Pattern:

The third pattern is used to display the zero values. If this pattern is omitted, the zero expression used in the first (positive) pattern will be applied. For example:

TDBNumber.DisplayFormat = "$####0.00"

' Positive: "$1234.00"

' Negative: "-$1234.00"

' Zero: "$0.00"

TDBNumber.DisplayFormat = "$#####.##"

' Positive: "$1234"

' Negative: "-$1234"

' Zero: "$"

However, if this pattern is specified, the default zero expression will be overridden:

TDBNumber.DisplayFormat = "$####0.00;;Zero"

' Positive: "$1234.00"

' Negative: "-$1234.00"

' Zero: "Zero"

TDBNumber.DisplayFormat = "$####0.00;;0"

' Positive: "$1234.00"

' Negative: "-$1234.00"

' Zero: "0"

The zero pattern also can be set using the braces ("{}") to fill a character into all number digits based on the display mask. Note that the keywords are treated as normal literally in this pattern.

TDBNumber.DisplayFormat = "$####0.00;;{#}"

' Positive: "$1234.00"

' Negative: "-$1234.00"

' Zero: "$#####.##"

TDBNumber.DisplayFormat = "$#####.##;;{#}"

' Positive: "$1234"

' Negative: "-$1234"

' Zero: "$#####.##"

TDBNumber.DisplayFormat = "$#####.##;;{}"

' Positive: "$1234"

' Negative: "-$1234"

' Zero: ""

Null Pattern:

Similar to the third pattern, the fourth pattern is used for expressing Null values. If this pattern is omitted, a zero-length string will be displayed in the control by default:

TDBNumber.DisplayFormat = "$####0.00"

' Positive: "$1234.00"

' Negative: "-$1234.00"

' Zero: "$0.00"

' Null: ""

TDBNumber.DisplayFormat = "$#####.##"

' Positive: "$1234"

' Negative: "-$1234"

' Zero: "$"

' Null: ""

However, if this pattern is specified, the default zero expression will be overridden:

TDBNumber.DisplayFormat = "$####0.00;;Zero;Null"

' Positive: "$1234.00"

' Negative: "-$1234.00"

' Zero: "Zero"

' Null: "Null"

TDBNumber.DisplayFormat = "$####0.00;;0;None"

' Positive: "$1234.00"

' Negative: "-$1234.00"

' Zero: "0"

' Null: "None"

Null patterns can also be set using the braces ("{}") to fill a character into all number digits based on the display mask. Note that the keywords are treated as normal literally in this pattern.

There may be cases when setting the input format to "###.##", that both the Zero and the Null expressions display a zero-length string in the control. But this will not effect the underlying value. The Value property will return the appropriate value accordingly. The text displayed in the control when losing the focus, can be retrieved with the DisplayText property.

The Format and the DisplayFormat properties will not affect the underlying value although the number of the digits specified in the formats differentiate from each other. For example:

TDBNumber.Format = "###,###.###"

TDBNumber.DisplayFormat = "##.#"

TDBNumber.Value = 123456.789

With the example above, the control displays "123456.7" when moving the focus to a different control, but the underlying value will be still set as "123456.789".

Resetting the input format will cause the underlying value to set to Null. The user would need to initialize the value after changing the Format property.

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