TcxCustomTextEditProperties.DisplayFormat Property

Specifies a formatting pattern for display text when the editor has no focus.

Declaration

property DisplayFormat: string read; write;

Property Value

Type	Description
string	The formatting pattern for editor display text.

Remarks

Use DisplayFormat and EditFormat properties to define formatting patterns for display text in inactive (display) and active (edit) modes. If the EditFormat property is unspecified, you can set the UseDisplayFormatWhenEditing property to True to apply the DisplayFormat formatting pattern to editor content in both modes.

Tip

DisplayFormat and EditFormat properties are useful if you need to change value formatting in a combo box, currency, spin, or any other editor that allows users to view and specify numeric values. For example, you can hide the zero value in a currency editor as demonstrated in the code example below.

Formatting Pattern Syntax

DisplayFormat and EditFormat properties use the numeric value formatting syntax found in the standard VCL library. A formatting pattern can include up to three sections delimited by semicolons that define formatting of positive, negative, and zero values. If the pattern includes only one section, the section affects all numeric values.

Each pattern section can include the following placeholders and separators:

0 | #

You can use either of these characters to define a digit placeholder in the formatting pattern.

.

Specifies the decimal point position. The TFormatSettings.DecimalSeparator global variable defines the actual decimal separator character.

,

Specifies the thousand separator position. The TFormatSettings.ThousandSeparator global variable defines the actual thousand separator character.

E+ | E- | e+ | e-

Specify scientific notation. You can add up to four digit placeholders after these characters to define the minimum number of digits in the exponent.

You can also add any quoted character sequence to the pattern to display this sequence as is in addition to a formatted number.

Refer to the TNumericField.DisplayFormat property description for detailed information on value formatting syntax in VCL.

Property Setter Behavior

The DisplayFormat property setter changes the AssignedValues.DisplayFormat property value to True once the change is applied to the editor outside a BeginUpdate/EndUpdate block or after an EndUpdate procedure call. To restore the initial DisplayFormat property value, you can set AssignedValues.DisplayFormat to False or call the AssignedValues.RestoreDefaults or RestoreDefaults procedure.

Code Example: Display Zero as an Empty Text Box

You can use the DisplayFormat property to hide a zero value in a currency editor.

The following code example sets the third section of the value formatting pattern to an empty string so an unbound currency editor displays a blank text box for 0 and Null Variant values:

Delphi

var
  AProperties: TcxCurrencyEditProperties;
begin
  AProperties := cxCurrencyEdit1.Properties;
  AProperties.BeginUpdate;  // Initiates the following batch change
  try
    AProperties.DisplayFormat := '$,0.00;($,0.00); ';  // Changes the default formatting pattern
    AProperties.UseDisplayFormatWhenEditing := True;  // Applies the same pattern in edit mode
    AProperties.AutoSelect := False;  // Disables automatic content selection in edit mode
  finally
    AProperties.EndUpdate;  // Calls EndUpdate regardless of the batch operation's success
  end;
end;

C++

  TcxCurrencyEditProperties *AProperties;
  // ...
  AProperties = cxCurrencyEdit1->Properties;
  AProperties->BeginUpdate();  // Initiates the following batch change
  try
  {
    AProperties->DisplayFormat = "$,0.00;($,0.00); ";  // Changes the default formatting pattern
    AProperties->UseDisplayFormatWhenEditing = true;  // Applies the same pattern in edit mode
    AProperties->AutoSelect = false;  // Disables automatic content selection in edit mode
  }
  __finally
  {
    AProperties->EndUpdate();  // Calls EndUpdate regardless of the batch operation's success
  }

Alternative Solution

You can set the UseNullString property to True and use the Nullstring property to define a custom formatting pattern if the edit value is Null Variant.

Default Value

Different terminal TcxCustomTextEditProperties class descendants define different default values for the DisplayFormat property.

For example, TcxCurrencyEdit and TcxDBCurrencyEdit controls use the cxFormatController.CurrencyFormat property value as the default DisplayFormat property value.

Refer to corresponding terminal TcxCustomTextEdit class descendants for detailed information.