How to Validate and Format Input with TAdvSpinEdit

TAdvSpinEdit: Complete Setup and Property Guide

Overview

TAdvSpinEdit is an advanced numeric input control (part of TMS Components for Delphi/C++Builder) that combines a spin edit with extended formatting, validation, and appearance options. This guide covers installation, placing the control on a form, important properties and events, common configuration patterns, and practical examples.

Installation & Setup

1. Install TMS Component Pack — Use the TMS installer or install from the provided packages (.bpl/.dpk). After installation, the TAdvSpinEdit component appears on the TMS or TAdv tab in the IDE component palette.
2. Add required units — In your unit’s uses clause add:

pascal
Copy CodeCopied
uses
AdvSpin, / core control /
  AdvStyles, / when using themes/styles /
  ...;

3. Place on form — Drop TAdvSpinEdit from the palette onto your form or create at runtime:

pascal
Copy CodeCopied
var
  Spin: TAdvSpinEdit;
begin
  Spin := TAdvSpinEdit.Create(Self);
  Spin.Parent := Self;
  Spin.Left := 16; Spin.Top := 16;
  Spin.Width := 120;
end;

Key Properties

• Value (Double/Extended) — Current numeric value. Use for reading/writing the control value.
• MinValue / MaxValue — Define allowed numeric range. The control enforces these on user input and up/down button changes.
• Increment — Amount added/subtracted when clicking the spin buttons or pressing arrow keys.
• DecimalPlaces — Number of decimal digits displayed.
• DisplayFormat — Format string for presenting the value (e.g., ‘0.00’, ‘#,##0.##’, currency formats).
• AllowEmpty — When True, permits blank input (useful when value is optional).
• ReadOnly — Prevents user edits but still allows programmatic changes.
• ButtonVisible / ShowUpDown — Controls visibility and placement of spin buttons.
• Alignment — Text alignment (taLeftJustify, taRightJustify, taCenter).
• WatermarkText / WatermarkColor — Placeholder text when empty.
• IncrementOnWheel — Whether mouse wheel changes value.
• ValidationOptions — Fine-tune behavior on invalid input (e.g., clamp to range, revert).
• Hint / ShowHint — Tooltip support.

Important Events

• OnChange — Triggered when Value changes (user or code). Good for immediate validation or syncing UI.
• OnValidate — Validate input before accepting; cancel or correct as needed.
• OnUpClick / OnDownClick — Custom behavior for spin buttons.
• OnKeyPress / OnKeyDown — Handle special key behavior (e.g., enter to commit).
• OnEnter / OnExit — Format value on focus change or parse user input.

Common Configuration Patterns

• Numeric currency input:

pascal
Copy CodeCopied
Spin.DisplayFormat := ‘0.00’;
Spin.DecimalPlaces := 2;
Spin.MinValue := 0;
Spin.MaxValue := 100000;
Spin.Increment := 0.50;

• Integer-only input:

pascal
Copy CodeCopied
Spin.DecimalPlaces := 0;
Spin.Increment := 1;
Spin.DisplayFormat := ‘0’;

• Optional value with watermark:

pascal
Copy CodeCopied
Spin.AllowEmpty := True;
Spin.WatermarkText := ‘Optional amount’;

Validation Strategies

• Simple range enforcement: set MinValue/MaxValue and ValidationOptions to clamp.
• Custom validation in OnValidate:

pascal
Copy CodeCopied
procedure TForm1.SpinValidate(Sender: TObject; var NewValue: Extended; var Accept: Boolean);
begin
  Accept := (NewValue >= 10) and (NewValue <= 500);
  if not Accept then
    ShowMessage(‘Value must be between 10 and 500.’);
end;

• Format on exit to ensure consistent display:

pascal
Copy CodeCopied
procedure TForm1.SpinExit(Sender: TObject);
begin
  Spin.Text := FormatFloat(’#,##0.00’, Spin.Value);
end;

Styling & Theming

• Use AdvStyles or VCL styles: set StyleElements or link a TAdvStyle or theme resource.
• Customize colors and fonts:

pascal
Copy CodeCopied
Spin.Font.Name := ‘Segoe UI’;
Spin.Font.Size := 10;
Spin.Color := clWindow;
Spin.WatermarkColor := clGrayText;

Accessibility & Keyboard

• Ensure TabStop = True and TabOrder is set appropriately.
• Support keyboard entry with Increment and Arrow keys; handle Enter to move focus or commit.

Runtime Tips

• Use BeginUpdate/EndUpdate if changing multiple properties to avoid flicker.
• For data-aware scenarios, bind to field and handle Null via AllowEmpty and ValueIsNull checks.
• When parsing user-entered strings, use TryStrToFloat/StrToFloat with FormatSettings for locale-aware decimal separators.

Troubleshooting

• Value not respecting DisplayFormat: ensure DecimalPlaces and DisplayFormat are consistent.
• Spin buttons not visible: check ButtonVisible/ShowUpDown and control width.
• Unexpected rounding: verify DecimalPlaces and Increment values; use Extended type for higher precision.

Example: Create a configured TAdvSpinEdit at runtime

pascal
Copy CodeCopied
var
  Spin: TAdvSpinEdit;
begin
  Spin := TAdvSpinEdit.Create(Self);
  Spin.Parent := Self;
  Spin.Left := 20; Spin.Top := 40; Spin.Width := 120;
  Spin.MinValue := 0; Spin.MaxValue := 1000; Spin.Value := 25;
  Spin.DecimalPlaces := 2; Spin.Increment := 0.25;
  Spin.DisplayFormat := ‘0.00’;
  Spin.OnValidate := SpinValidate;
end;

Summary

TAdvSpinEdit offers precise numeric input control with rich formatting, validation, and styling options. Configure MinValue/MaxValue, DecimalPlaces, Increment, and DisplayFormat for predictable behavior; use OnValidate and OnChange for custom rules; and apply themes or fonts for consistent UI. With these settings you can adapt TAdvSpinEdit for currency, integer-only fields, optional values, and more.