Provides extended TSpinEdit- and TFloatSpinEdit-like controls.

Implements TSpinEditEx and TFloatSpinEditEx, which allow a NullValue and provide behaviors applied when the text for the control is not a valid number.

Initial implementation: 2016 by Bart Broersma. Revised in August 2020.

spinex.pps is part of the LazControls package.

Specifies the behavior applied in a control when its text is not a valid number.

TNullValueBehaviour is an enumerated type with values that control the behavior in TSpinEditEx or TFloatSpinEditEx when their value is not a valid number, or not within the Min and Max value for the control.

Value becomes NullValue, and Text becomes empty. TextHint will show when focus is lost.
Value becomes GetLimitedValue(NullValue), and Text becomes Value.
Value becomes MinValue, and Text becomes Value. Please note that this is the default behavior, as used in Delphi.
Value becomes MaxValue, and Text becomes Value.
Value becomes InitialValue (OnEnter), and Text becomes Value.
Specifies the base class for extended spin edit controls in the unit.

TSpinEditExBase is a generic class type, and a descendant of TCustomAbstractGroupedEdit. TSpinEditExBase specifies the base class for the extended spin edit controls including TSpinEditEx and TFloatSpinEditEx. TSpinEditExBase must be specialized in a descendent class for a specific data type. The specialization type is used to implement properties including: Increment, MinValue, MaxValue, NullValue, and Value.

Default value for the Increment property.
Default value for the MaxValue property.
Default value for the MinValue property.
Default value for the MinRepeatValue property.
Gets the value for the Edit property.
Value for the property.
Sets the value for the MinRepeatValue property.
New value for the property.
Called when one of the buttons in the TUpDown control has been clicked.

SpinUpDown ensures that the value in Text is a valid representation for the numeric type used in the control. It calls GetLimitedValue to ensure that Value is in the range specified in MinValue and MaxValue. MinValue is used if TextIsNumber returns False.

SpinUpDown sets the value in Modified to True when Value has been updated in the method.

Called when key or mouse events are handled in EditKeyDown, EditMouseWheelDown, and EditMouseWheelUp. It is also assigned as the handler routine for the OnChangingEx event in the UpDown property in the constructor for the class instance.

True when the Up button in the TUpDown control has been clicked; False when the Down button has been clicked.
Gets the value for the NullValue property.
Returns the generic type with the value for the NullValue property.
Gets the value for the Orientation property.
Value for the Orientation property.
Gets the value for the UpDown property.
Value for the property.
Gets the value for the Value property.
Value for the property.
Gets the storage specifier for the Increment property.
True when a value other than DefIncrement has been assigned to the Increment property.
Determines if the specified value is not within the limits set in MinValue and MaxValue.
True when the value is outside the limits specified in the MinValue and MaxValue properties.
Value examined in the method.
Gets the storage specifier for the MaxValue property.
True when a value other than DefMaxValue has been assigned to the MaxValue property.
Gets the storage specifier for the MaxValue property.
True when a value other than DefMaxValue has been assigned to the MinValue property.
Sets the value for the Orientation property.
New value for the Orientation property.
Implements the OnChangingEx event handler assigned to UpDown.

No actions are performed in the handler when ReadOnly is set to True.

When Direction is updUp, the SpinUpDown method is called using True as an argument. Otherwise, SpinUpDown is called using False as an argument.

Control for the event notification.
Not used in the method.
Not used in the method.
Indicates whether the up or down button was clicked in UpDown.
Implements the OnClick event handler assigned to UpDown.

Calls the BuddyClick method for the grouped edit control.

Control for the event notification.
The button type for the TUpDown control.
Gets the class type used for Buddy in the grouped edit control.
Returns a class reference to TUpDown.
Performs actions needed when the control is focused.

DoEnter is an overridden method in TSpinEditExBase, and calls the inherited method on entry. The inherited methods handle the change in control focus, and signal the OnEnter event handler (when assigned). DoEnter ensures that the initial Value for the control is stored internally for use with the NullValueBehaviour used for the control instance.

Gets the text displayed for the control.

RealGetText is an overridden TCaption function in TSpinEditExBase used to get the text displayed for the control. RealGetText checks whether a handle has been allocated for the control in the widget set class. When a handle is assigned, the inherited method is called to the Text for the Edit in the grouped edit control. Otherwise, ValueToStr is called to get the string representation for the control Value.

TCustomAbstractGroupedEdit.RealGetText
Contains the text with the value for the control.
Reverts changes made to the value for the control.

Reset is an overridden method in TSpinEditExBase used to revert changes made to the Value for the control. The IsMasked property is used to determine if an editing mask is in use in the Edit for the grouped edit control. When set to True, the inherited method is called to revert any changes made in Edit. When an editing mask is not in use, the initial value for the control (captured when it received focus) is restored in the Value property.

Reset is used in the implementation of the EditKeyDown event handler assigned to Edit. It is called when the Escape key (VK_Escape) is pressed in the Edit control.

Signals the OnChange event handler for the Edit in the grouped edit control.

EditChange is an overridden method in TSpinEditExBase. It ensures that Modified is set to True when Value has been changed using the UpDown buttons, Up or Down cursor keys, or by scrolling the mouse wheel. EditChange calls the inherited method prior to exit to signal the OnChange event handler (when assigned).

Implements the KeyDown handler for the grouped edit control.

EditKeyDown is an overridden method in TSpinEditExBase which implements the KeyDown event handler for the Edit control. It calls the inherited method which signals the OnKeyDown event handler (when assigned). It also ensures that any keys explicitly handled in the grouped edit control are discarded by setting Key to 0 (zero). This includes the following virtual key codes and their associated actions:

VK_Escape
  Calls Reset.
VK_Up
  Calls SpinUpDown when ArrowKeys is set to True and the control is not ReadOnly.
VK_Down
  Calls SpinUpDown when ArrowKeys is set to True and the control is not ReadOnly.

Virtual key code examined in the handler.
Shift, Ctrl, or Alt modifier for the key code.
Applies a Mouse Wheel Up message to the value for the control.

EditMouseWheelUp is the handler signalled when a Mouse Wheel Up message occurs in the Edit for the control. EditMouseWheelUp is overridden in TSpinEditExBase, and calls the inherited method. Handled is set to True if the mouse wheel message was handled in the ancestor class. When set to False, the SpinUpDown method is called to increment the value in the control.

Shift, Alt, or Ctrl modifier for the mouse wheel message.
Coordinates for the Mouse pointer.
True when the message is handled in the ancestor class.
Handles mouse wheel down messages for the Edit in the control.

EditMouseWheelDown is the handler signalled when a Mouse Wheel Down message occurs in the Edit for the control. EditMouseWheelDown is overridden in TSpinEditExBase, and calls the inherited method. Handled is set to True if the mouse wheel message was handled in the ancestor class. When set to False, the SpinUpDown method is called to decrement the value in the control.

Shift, Alt, or Ctrl modifier for the mouse message.
Coordinates for the mouse cursor.
True when the message was handled in the method.
Indicates if valid values have been assigned to the MinValue and MaxValue properties.

The return value is True when MaxValue is larger than MinValue. IsLimited is used in the implementation of the IsOutOfLimits method.

True when the typed value in MaxValue is larger than the typed value in MinValue.
Ensures the incremented value is a valid number for the data type.

SafeInc is a function used to increase the specified value by the Increment for the control. SafeInc ensures that the incremented value is valid for a given data type. It is an abstract virtual method, and must be implemented in a descendent class to use the specific data type for the specialization.

AValue contains the type with the numeric value to be incremented.

The return value contains the numeric value for the type after the value in Increment has been added. The return value is constrained when the incremented value is too large for the data type.

SafeInc is used in the implementation of the SpinUpDown method.

The incremented (and possibly constrained) value.
Value incremented in the method.
Ensures the decremented value is a valid number for the data type.

SafeDec is a function used to decrease the specified value by the Increment for the control. SafeDec ensures that the decremented value is valid for a given data type. It is an abstract virtual method, and must be implemented in a descendent class to use the specific data type for the specialization.

AValue contains the type with the numeric value to be decremented.

The return value contains the numeric value for the type after the value in Increment has been subtracted. The return value is range limited when the incremented value is too large for the data type.

SafeDec is used in the implementation of the SpinUpDown method.

Control value after the decrement operation.
The decremented (and possibly range limited) value.
Determines whether the specified arguments have the same value.

SameValue is a Boolean function used to compare the values in AValue1 and AValue2 to determine if they have the same value. The return value is True when both AValue1 and AValue2 have the same value. It is defined as an abstract virtual method in TSpinEditExBase, and must be implemented in descendent classes to compare the data type for the specialization.

SameValue is used in the implementation of storage specifiers for the Increment, MinValue, and MaxValue properties.

This method was introduced to ensure that the type specialization for the class instance is used when value comparisons are performed.

Introduced in version 2.2.0. Modified in version 3.0 to remove the define for FPC compiler version.
Math.SameValue
True if both arguments have the same value.
First value for the comparison.
Second value for the comparison.
Sets the value for the Value property.
New value for the property.
Sets the value for the NullValue property.
New value for the property.
Sets the value for the MaxValue property.
New value for the property.
Sets the value for the MinValue property.
New value for the property.
Sets the value for the Increment property.
New value for the property.
Indicates if the specified String contains a valid numeric value.

TextIsNumber is an abstract virtual Boolean function which indicates the value specified in S represents a valid number. ANumber is an output parameter where the numeric value for the data type is stored.

TextIsNumber must be implemented in a descendent class using the data type for the specialization.

True when S contains a value that can be converted to the data type for ANumber.
String converted to a numeric value in the method.
Numeric value for the specified String.
Updates members in the control when editing is completed.

UpdateControl is a method used to update members in the class instance to reflect the state for the control. It is called when a new value is assigned to properties in the class instance. It is called when editing has been completed using the Edit for the grouped editing control. It is also called when the handle is allocated for the control in InitializeWnd.

NullValueBehaviour is used to determine whether Value is adjusted to ensure that it is in the range specified by MinValue and MaxValue. A value other than nvbShowTextHint causes GetLimitedValue to be called to get the adjusted Value.

No additional actions are performed in the method when a handle has not been allocated for the control, or at design-time.

When NullValueBehaviour is set to nvbShowTextHint, an invalid numeric value entered in Text causes Text to be set to an empty string. This allows the TextHint for the control to be displayed.

When Value is a valid number, and in the required range, it is converted to its String representation and assigned to the Text for the control.

Performs actions needed when the handle is allocated for the control.

InitializeWnd is an overridden method used to perform actions needed when the handle is allocated for the control, and before child controls are created. InitializeWnd calls the inherited method on entry.

InitializeWnd updates the value in the Text property by calling ValueToStr. This ensures that the Value property is range-limited to the settings in MinValue and MaxValue (when needed). InitializeWnd calls UpdateControl to validate and update members in the class instance using NullValue and NullValueBehavior (when needed).

TCustomAbstractGroupedEdit.Text TWinControl.InitializeWnd
Performs actions prior to freeing the handle for the control.

Ensures that the Value property is up-to-date before releasing the Handle for the control.

TWinControl.FinalizeWnd
Performs action needed when the component has been loaded from the LCL streaming mechanism.

Loaded is an overridden method in TSpinEditExBase, and calls the inherited method on entry. Loaded corrects an undesirable behavior in the ancestor class; it sends a CM_PARENTFONTCHANGED message which also alters the color in the grouped edit control. Loaded calls UpdateSpacing prior to restoring the initial color assigned to the edit control.

Indicates is Up and Down cursor keys can be used in the Edit for the control

ArrowKeys is a Boolean property which indicates if cursor keys can be used to navigate content in the Edit for the control.

When set to True, the Up (VK_UP) and Down (VK_Down) arrow keys can be used to increase or decrease the Value for the control. The key events are handled in the EditKeyDown event handler assigned to Edit. When set to False, the Up and Down keys are ignored in Edit.

The default value for the property is True.

Use UpDown to access the TUpDown instance used in the grouped edit control.

Text editor for the grouped edit control.

Edit a read-only TGEEdit property which contains the editor for the grouped edit control. Edit is used to perform direct input of a new Value for the control. Edit allows use of the Up and Down cursor keys to increment or decrement the value when ArrowKeys is enabled.

UpDown is the TUpDown instance used to increment and decrement the value for the grouped edit control using mouse clicks.

Contains the TUpDown instance used in the grouped edit control.

UpDown is a read-only property which contains the TUpDown instance used to increment or decrement the Value for the grouped edit control. Click on the buttons in UpDown to increase or decrease the Value for the control by the amount specified in the Increment property.

Edit is used to perform direct input of the value for the grouped edit control.

Indicates whether the TUpDown instance for the grouped edit control is visible.

UpDownVisible is a Boolean property which indicates if UpDown in the grouped edit control is visible. It is a convenience property; read and write access for the value are redirected to the Visible property in the TUpDown instance in UpDown. The default value for the property is True.

Contains the repeat interval for the TUpDown instance in the grouped edit control.

MinRepeatValue contains the repeat interval used for the UpDown control in the grouped edit. The default value for the property is defined in the DefMinRepeatValue constant.

Changing the value for the property causes the MinRepeatInterval property in UpDown to be updated with the new value.

Controls the orientation for the increment and decrement buttons used to change the value for the control.

Orientation is a TUDOrientation property which determines the orientation for the buttons on the associated control used to change the Value property. The property value is read from and written to the UpDown property which is the Buddy (associate) in the grouped edit control.

The default value for the Orientation property is udVertical, and causes the buttons to be stacked vertically on the edge of the control where the buttons are aligned. The increment button in placed above the decrement button. Each button uses one half of the Height for the control excluding the spacing between the buttons.

udHorizontal causes the buttons to be displayed side-by-side on the edge of the control where the buttons are aligned. The decrement button is placed to the left of the increment button. Each button has the same width and mirrors the height for the control. This causes the buttons to have a larger visual footprint than when the vertical orientation is used.

Changing the value for the property causes the UpDown control to be updated with the new property value, and the Width in the UpDown control is adjusted for the new orientation.

Use the Layout property to control the position of the Edit box within the grouped edit control. Use UpDownVisible to display or hide the TUpDown Buddy control for the grouped edit control.

TUpDown.Orientation TUDOrientation TCustomAbstractGroupedEdit.Buddy TCustomAbstractGroupedEdit.Layout
Width for the spin buttons on the grouped edit control.

SpinButtonWidth is an Integer property which controls the width for the spin buttons displayed for the control. The value for the property is read from and written to the Width for the Buddy property on the grouped edit control. The initial value for the property is the default width assigned to the control in UpDown (17 pixels at 96ppi).

SpinButtonWidth allows the width for the buttons to be maintained when the control is auto-sized and the spin buttons are too wide or too narrow for the resulting control height. In general, the width of the spin buttons should be increased when the font size is increased or reduced when the font size is reduced.

Use AutoSize to resize the height for the control when the Font size is changed.

Use AutoSizeHeightIsEditHeight to set the preferred height for the grouped edit control to the preferred height for the text edit on the control when AutoSize is enabled.

Added to LazControls in LCL version 4.0.
TCustomAbstractGroupedEdit.AutoSize TCustomAbstractGroupedEdit.AutoSizeHeightIsEditHeight TCustomAbstractGroupedEdit.GetBuddyWidth TCustomAbstractGroupedEdit.SetBuddyWidth TCustomAbstractGroupedEdit.Buddy
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry. Create sets the default values for properties, including:

- ArrowKeys
- Increment
- MaxValue
- NullValueBehaviour
- MinRepeatValue

Create configures the Edit and UpDown instances used in the grouped edit control. Edit is configured to use right alignment for its text (since it is a numeric value). UpDown is configured to include the flags needed in its ControlStyle property. The OnChangingEx and OnClick event handlers for UpDown are also set in the method.

UpDown does not use its Associate property to maintain the relationship to Edit. This is by design, and allows Edit to be used with floating point numbers and have a NullValue (in a descendent class instance). It also enables proper alignment and anchoring for the grouped edit control.

Internal members needed in the class instance are also initialized.

Create calls SetInitialBounds to set the size for the control to the default values returned from GetControlClassDefaultSize.

Owner of the class instance.
Constrains the specified value to MinValue and MaxValue for the control.

GetLimitedValue is used in the implementation of UpdateControl, SpinUpDown, and StrToValue methods. It is also called from the ValueToStr method in TCustomFloatSpinEditEx.

GetLimitedValue ensures that the value for the type specified in AValue is constrained to the range specified in the MinValue and MaxValue properties.

The return value contains the original value after it has been range adjusted. When AValue is smaller than MinValue, MinValue is assigned to the return value. When AValue is larger than MaxValue, MaxValue is assigned to the return value.

The return value is not range adjusted when MinValue and MaxValue have the same value. This is Delphi VCL compatible.
Value adjusted (when needed) to the MinValue and MaxValue constraints.
Value examined (and adjusted when needed) in the method.
Converts the specified value to its representation as a String.

ValueToStr is an abstract virtual String function used to convert the value specified in AValue to its representation as a String data type. ValueToStr must be implemented in a descendent class to use the data type and formatting needed for the specialization.

String representation for the specified data type.
Type with the numeric value converted in the method.
Converts the specified string to a numeric value for the generic data type.

StrToValue is a function which returns a generic type with the numeric value for the specified String. TextIsNumber is used to determine if S contains a valid numeric value. If S is not a valid number, the NullValueBehaviour property is used to determine the return value for the method.

nvbShowTextHint
  NullValue is used as the return value.
nvbLimitedNullValue
  GetLimitedValue is used to derive the Null return value.
nvbMinValue
  MinValue is used as the return value.
nvbMaxValue
  MaxValue is used as the return value.
nvbInitialValue
  The initial value for the control is used as the return value.
nvbShowTextHint
  GetLimitedValue is used to get the return value

Numeric value for the specified string.
String representation converted in method.
Implements the EditingDone handler for the Edit in the grouped edit control.

EditEditingDone is an overridden method in TSpinEditExBase. It calls the inherited method on entry to signal the OnEditingDone event handler (when assigned).

EditEditingDone updates the Value for the control from the Text in the Edit. UpdateControl is called to ensure that members in the property are updated and validated after a change to the Value property.

Value added to or subtracted from Value when the UpDown control is clicked.

Increment is a property which defines the value added to or subtracted from the control Value when the UpDown control is clicked. It is also used when ArrowKeys are enable in the Edit for the grouped edit control.

Increment uses the generic type for the class instance. There is no default value for the control in TSpinEditExBase, but it may be re-specified in a descendent class specialized for a given data type.

Minimum value allowed in the Value property.

MinValue is a property used to specify the minimum numeric value allowed in the Value property. MinValue uses the type specified for the generic class.

Use MaxValue to specify the upper limit for the value in the control.

MinValue is used, along with MaxValue, to ensure that the Value property falls within the specified limits. MinValue and MaxValue are not enforced when they have not been explicitly assigned, if they contain the same value, or when MaxValue is smaller than MinValue. This allows any numeric value to be assigned to the control.

MinValue is used in the implementation of private methods such as IsLimited, IsOutOfLimits, and SpinUpDown. It also influences the value stored in the control when GetLimitedValue or NullValueBehaviour is applied.

Maximum value allowed in the Value property.

MaxValue is a property used to specify the largest numeric value allowed in the Value property. MaxValue uses the type specified for the generic class.

Use MinValue to specify the lower limit for the value in the control.

MaxValue is used, along with MinValue, to ensure that the Value property falls within the specified limits. MinValue and MaxValue are not enforced when they have not been explicitly assigned, if they contain the same value, or when MaxValue is smaller than MinValue. This allows any numeric value to be assigned to the control.

MaxValue is used in the implementation of private methods such as IsLimited, IsOutOfLimits, and SpinUpDown. It also influences the value stored in the control when GetLimitedValue or NullValueBehaviour is applied.

Value used when the text for the control is not a valid number.

NullValue contains the numeric value used when the text for the control does not represent a valid number. NullValue is assigned to Value when the NullValueBehaviour property is set to nvbLimitedNullValue or nvbShowTextHint.

Controls the logic applied when control text is not a valid number.

NullValueBehaviour is a TNullValueBehaviour property which contains the logic applied when the text for the control does not represent a valid numeric value. The default value for the property is nvbMinValue, and indicates that the value in MinValue is stored in the Value property when an invalid number is detected.

See TNullValueBehaviour for more information about values in the enumeration and their meanings.

NullValueBehaviour is used in the implementation of the UpdateControl and StrToValue methods.

Numeric value for the control.

Value is a property which contains the numeric value for the spin edit control. Value uses the data type specified for the generic class.

If a valid Handle has been allocated for the control, the property value is retrieved by calling StrToValue using the Text for the control. If the handle has not been allocated, the value stored in the internal member is used.

Setting a new value for the property ensures that text assigned directly to Edit contains a valid number for the data type. This is done by calling TextIsNumber. If the new value is the same as the stored property value, no actions are performed.

When the property value is changed, it is range checked and validated. Use MinValue and MaxValue to control the minimum and maximum values allowed in the control. The range limits are not enforced if they have not been explicitly assigned, contain the same value, or when MaxValue is smaller than MinValue.

Use Increment to control the amount applied to the control value when a button in the UpDown control is clicked. Use NullValue and NullValueBehaviour to control the logic applied with an invalid numeric value is stored in the control.

Indicates the display mode used for the floating point value in TFloatSpinEditEx.
Value is displayed with fixed precision and decimal places.
Value is displayed in scientific (exponential) notation used for numbers that are too large or too small to be easily represented using the decimal form.
Value is automatically formatted using scientific notation when it exceeds the limits assigned in ExponentialFormatLimitPos or ExponentialFormatLimitNeg.
When Value is 0.0, it is formatted using 20 digits of fixed precision with the number of decimals in DecimalPlaces. Similar to dmAuto but using fixed precision.
A specialization of TSpinEditExBase for the Double data type.

TCustomFloatSpinEditEx defines an extended spin edit control with an editor for the numeric value, and buttons to increment or decrement the control value.It is a TSpinEditExBase descendant which specializes the generic ancestor for the Double data type. Double is a real type which allows values in the range 5.0E-324 .. 1.7E+308 and uses 15-16 digits of precision. Double is used to implement properties including: Increment, MinValue, MaxValue, NullValue, and Value.

Do not create instances of TCustomFloatSpinEditEx; use the TFloatSpinEditEx descendant which sets the visibility and default values for properties in the class.

The NumbersOnly property has been removed as a published property in TCustomFloatSpinEditEx and its descendent classes. It is not appropriate for use in floating point notation. Removed in LazUtils version 2.3.0.
Default number of decimal places used to display the Value for the control.
Default decimal separator used in the floating point value.
Number of decimal places used to display the Value for the control.
Formatting used to edit and display the Value for the control.
Number of digits displayed in an exponent using scientific notation.
Maximum exponent digits allowed before exponential notation is used for negative values.
Maximum exponent digits allowed before exponential notation is used for positive values.
Local format settings used in the control.
Number of digits of precision used to edit and display the Value for the control.
Gets the value for the DecimalSeparator property.
Value for the property.
Sets the value for the DecimalSeparator property.
New value for the property.
Sets the value for the DisplayMode property.
New value for the property.
Sets the value for the ExponentDigits property.
New value for the property.
Sets the value for the ExponentialFormatLimitNeg property.
New value for the property.
Sets the value for the ExponentialFormatLimitPos property.
New value for the property.
Sets the value for the Precision property.
New value for the property.
Gets the local format settings for the control.
Local format settings used for the control.
Implements handler for KeyPress events in the Edit for the control.

EditKeyPress is an overridden method in TCustomFloatSpinEditEx used to ensure that the specified character is valid for the Edit in the control. Key contains the character examined in the method. The allowed values in Key include the following characters:

Numeric Digits
  Characters in the range '0'..'9'.
Decimal separator
  Accepts either ',' (Comma), or '.' (Period) characters as the decimal separator, and is automatically translated to the value used in local format settings in the DecimalSeparator property. Any decimal separator will, however, be discarded when DecimalPlaces is set to 0 (zero).
Exponent Notation
  Allows 'E' or 'e' to represent the exponent character used to represent "... times ten raised to the power of ...".
Control Characters
  Allows the following control characters to be passed to the Edit control: #8 (BackSpace), #9 (Tab), ^C (Ctrl+C or Copy), ^X (Ctrl+X or Cut), ^V (Ctrl+V or Paste), ^Z (Ctrl+Z or Undo).

EditKeyPress calls the inherited method to signal the OnKeyPress event handler (when assigned).

Any character which is not allowed in the floating point value is set to #0 to discard the character value.

Character examined in the method.
Determines if the specified string is a valid number for the numeric data type.

TextIsNumber is an overridden Boolean function used to determine if the specified string contains a valid representation for the numeric data type in the control. TextIsNumber re-implements the inherited method to use the Double data type, and does not call the method in the ancestor class.

TextIsNumber calls TryStrToFloat using the local format settings for the control to convert the value in S to a floating point value. An exception raised by TryStrToFloat is handled in the method. The converted numeric value is stored in the ANumber argument on success. ANumber should be considered "undefined" when the conversion fails due to an exception.

The return value is True when the value in S can be converted to the Double data type. It is False when an exception was raised and handled in the method.

TextIsNumber is used in the implementation of methods like UpdateControl, SpinUpDown, and StrToValue. It is also called when setting a new value in the Value property.

Set values in the MinValue, MaxValue, NullValue, and NullValueBehaviour properties to control the actions performed when TextIsNumber returns False.

True if the specified string is a valid numeric value.
String with the value examined in the method.
Stores the numeric value for the specified string; undefined when the result is False.
Ensures the incremented value is a valid number for the Double data type.

SafeInc is an overridden function in TCustomFloatSpinEditEx used to increase the specified value by the Increment for the control. SafeInc ensures that the incremented value is valid for the Double data type. SafeInc does not call the inherited method.

AValue contains the type with the numeric value to be incremented.

The return value contains the numeric value after the value in Increment has been added. The return value is constrained when the incremented value is too large for the Double data type. The upper limit for the value in the data type is defined in the MaxDouble constant.

SafeInc is used in the implementation of the SpinUpDown method.

SafeDec is used to decrement a specified Double value.

The numeric value after Increment has been added.
Numeric value incremented in the method.
Ensures the decremented value is a valid number for the Double data type.

SafeDec is an overridden function in TCustomFloatSpinEditEx used to decrease the specified value by the Increment for the control. SafeDec ensures that the decremented value is valid for the Double data type. SafeDec does not call the inherited method.

AValue contains the type with the numeric value to be decremented.

The return value contains the numeric value after the value in Increment has been subtracted. The return value is constrained when the decremented value is too small for the Double data type. The lower limit for the value in the data type is defined as -1 * MaxDouble.

SafeDec is used in the implementation of the SpinUpDown method.

SafeInc is used to increment a specified Double value.

The numeric value after Increment has been subtracted.
Numeric value decremented in the method.
Determines whether the specified arguments have the same value.

SameValue is an overridden Boolean function used to compare the values in AValue1 and AValue2 to determine if they have the same value. The return value is True when both AValue1 and AValue2 have the same value. The arguments are implemented using the Double type in TCustomFloatSpinEditEx. The overloaded SameValue routine in the math.pp unit is called to get the return value for the method.

This method was introduced to ensure that the type specialization for the class instance is used when value comparisons are performed.

Introduced in version 2.2.0. Modified in version 3.0 to remove the define for FPC compiler version.
Math.SameValue
True if both arguments have the same value.
First value for the comparison.
Second value for the comparison.
Sets the value for the DecimalPlaces property.
New value for the property.
Registers the widget set class used for the control.

Calls the inherited method on entry, and registers the following properties to be skipped during LCL component streaming:

NumbersOnly
  Property should not be published for this control.

Added in LazUtils version 2.3.0 and higher.
Specifies the formatting used to edit and display the Value for the control.

DisplayMode is a TDisplayMode property which specifies the formatting used to edit and display the Value for the control. The default value for the property is dmFixed, and indicates that fixed precision and decimals are used when formatting the control value.

See TDisplayMode for more information about the values and meanings in the enumeration.

Changing the value in DisplayMode causes the Value for the control to be updated. It also forces UpdateControl to be called to validate and normalize members in the class instance.

DisplayMode is used in the implementation of the ValueToStr method which generates the string representation for the Value in the control, and is assigned to the Text property in the Edit for the grouped edit control.

Maximum exponent digits allowed before exponential notation is required for a positive number.

ExponentialFormatLimitPos is an Integer property which contains the maximum exponent allowed before a positive Value in the control must be represented using exponential notation. The default value for the property is 6 (six) and indicates that Value must exceed 10^6 before exponential notation is required for a positive number.

Setting a new value for the property causes Value to be updated, and calls the UpdateControl method to validate and normalize members in the class instance.

ExponentialFormatLimitPos is used in the ValueToStr method when DisplayMode contains the value dmAuto and Value has a non-zero floating point value.

Use ExponentialFormatLimitNeg to specify the maximum exponent allowed before using exponential notation for a negative value in the control.

Use Precision to specify the total number of digits used for a number in scientific notation. Use ExponentDigits to specify the number of exponent digits used for a number in scientific notation.

Maximum exponent digits allowed before exponential notation is required for a negative number.

ExponentialFormatLimitNeg is an Integer property which contains the exponent value at which use of scientific notation is triggered for a negative Value in the control. The default value for the property is -6, and indicates that scientific notation is required when Value is smaller than 10^-6.

Changing the value for the property causes GetValue and UpdateControl to be called.

ExponentialFormatLimitNeg is used in the ValueToStr method when DisplayMode is dmAuto and the Value is not 0.0.

Use ExponentialFormatLimitPos to specify the exponent value which triggers use of scientific notation for a positive value.

Use Precision to specify the total number of digits used for a number in scientific notation. Use ExponentDigits to specify the number of exponent digits used for a number in scientific notation.

Number of digits of precision used after the decimal point in scientific notation.

Precision is an Integer property which specifies the number of digits of precision used after the decimal point for a floating point value in scientific notation. It is the value used as the precision argument for the FloatToStrF routine in RTL. The default value for the property is 6. The maximum precision for the data type is 15.

Changing the value for the property causes the GetValue and UpdateControl methods to be called.

Precision is used in the ValueToStr method when DisplayMode is dmScientific or dmAuto.

Number of digits prior to the decimal point used in scientific notation.

ExponentDigits is an Integer property which contains the number of digits used before the decimal point when using scientific notation. The default value for the property is 2.

Changing the value for the property causes the GetValue and UpdateControl methods to be called.

ExponentDigits is used in the ValueToStr method when the DisplayMode is dmScientific or dmAuto.

Use Precision to specify the number of digits after the decimal point in a floating point value using scientific notation.

Gets the string representation for the numeric Value in the control.
String representation for the numeric Value.
Numeric value examined and converted in the method.
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry.

Create makes an internal copy of the default format settings for the platform. This allows the value in DecimalSeparator to be specified and stored independent of the value in DefaultFormatSettings. The local copy is modified to used the value in the DefDecimalSeparator constant as the default value for DecimalSeparator.

Create sets the default values for properties, including:

DecimalPlaces
  Set to the value in the DefDecimals constant.
ExponentialFormatLimitPos
  Set to 6 (six).
ExponentialFormatLimitNeg
  Set to -6.
Precision
  Set 6 digits for the mantissa.
ExponentDigits
  Set to 2.
DisplayMode
  Set to the value dmFixed for fixed format using the Precision and ExponentDigits defined in the control.

Value used to represent a decimal point in the Edit control.

DecimalSeparator is a Char property which contains the character used as the decimal point in a floating point value. Read and write access for the property value are redirected to the local TFormatSetting stored in the class instance. This allows the control to set the decimal separator independent of the format settings for the platform or operating system.

The default value for the property is defined in the DefDecimalSeparator constant. Changing the value for the property updates the local format settings, and calls UpdateControl to validate and update members in the class instance.

DecimalSeparator is used in EditKeyPress to validate characters entered in the Edit for the control. It is also used in ValueToStr to format the value in the control for the selected DisplayMode.

Number of decimal places used to edit and display the Value for the control.

DecimalPlaces is an Integer property which indicates the number of decimal places used when formatting the Value for the control. It must contain a positive integer value or 0 (zero). The default value for the property is defined in the DefDecimals constant. Changing the value for the property causes the Value property to be updated, and calls UpdateControl to validate and update other members in the class instance.

DecimalPlaces is used in ValueToStr to format the value in the control for the selected DisplayMode.

Implement a spin edit control for a value using the Double data type.

TFloatSpinEditEx is a TCustomFloatSpinEditEx descendant which implements a spin edit control for a value using the Double data type. TFloatSpinEditEx sets the visibility for properties defined in ancestor classes.

TFloatSpinEditEx defines an extended spin edit control with an editor for the numeric value, and buttons to increment or decrement the control value. It specializes the generic ancestor for the Double data type. Double is a real type which allows values in the range 5.0E-324 .. 1.7E+308 and uses 15-16 digits of precision. Double is used to implement properties including: Increment, MinValue, MaxValue, NullValue, and Value.

Defines the base class for a spin edit control for Int64 values.

TCustomSpinEditEx is a specialization of the generic TSpinEditExBase class for the Int64 data type. In addition to implementing the Int64 data type, it provides additional properties and methods used to validate, format, and display the numeric value.

Use the ThousandSeparator to set the UTF-8-encoded value used as the decimal point in the control value.

Set Increment to the value by which the control is increased or decreased when the UpDown button is clicked.

Use ValueToStr to get the string representation for the numeric value.

Do not create instances of TCustomSpinEditEx; use TSpinEditEx, which sets the visibility for properties, instead.

Use TFloatSpinEditEx to edit a floating point value using fixed or scientific notation.

Stores the thousands separator.
Sets the value for the ThousandSeparator property.
New value for the property.
Implements the handler for KeyPress events in the Edit for the control.

EditKeyPress is an overridden method in TCustomSpinEditEx, and calls the inherited method on entry. The OnKeyPress event handler is signalled (when assigned) by the inherited method.

EditKeyPress ensures that the value in Key is valid for the control. An invalid value is discarded by setting Key to the #0 character (Decimal 0). Valid characters include numeric digits ('0'..'9'), the value in ThousandSeparator, and the negative sign indicator ('-').

Please note: The sign indicator will be disallowed when a positive non-zero value is specified in the MinValue property.

Tab, BackSpace, Cut, Paste, Copy, and Undo key presses are passed to the inherited method.

Character examined in the method.
Ensures the incremented value is valid for the data type.

SafeInc is a function used to increase AValue by the amount specified in the Increment property. SafeInc is overridden in TCustomSpinEditEx to ensure that the incremented value is valid for the Int64 data type.

AValue contains the numeric value to be incremented.

The return value contains the Int64 value after Increment has been added. The return value is constrained when the incremented value is too large for the Int64 data type; its value is set to High(Int64).

SafeInc is used in the implementation of the SpinUpDown method in the ancestor class.

Numeric value after the increment has been added.
Numeric value incremented in the method.
Ensures the decremented value is valid for the data type.

SafeDec is a function used to decrease the specified value by the amount specified in the Increment property. SafeDec is overridden in TCustomSpinEditEx to ensure that the decremented value is valid for the Int64 data type.

AValue contains the numeric value to be decremented.

The return value contains the Int64 value after Increment has been subtracted. The return value is constrained when the decremented value is too small for the Int64 data type; its value is set to Low(Int64).

SafeDec is used in the implementation of the SpinUpDown method in the ancestor class.

"
Numeric value after the increment has been subtracted.
Numeric value decremented in the method.
Determines whether the specified arguments have the same value.

SameValue is an overridden Boolean function used to compare the values in AValue1 and AValue2 to determine if they have the same value. The return value is True when both AValue1 and AValue2 have the same value. The arguments are implemented using the Int64 type in TCustomSpinEditEx.

This method was introduced to ensure that the type specialization for the class instance is used when value comparisons are performed.

Introduced in version 2.2.0. Modified in version 3.0 to remove the FPC version compiler define.
Math.SameValue
True if both arguments have the same value.
First value for the comparison.
Second value for the comparison.
Indicates if the specified String contains a valid Int64 data type.

TextIsNumber is an overridden Boolean function which indicates if the value specified in S represents a valid number for the Int64 data type.

ANumber is an output parameter where the numeric value from the conversion from the is stored.

The return value is a Boolean type which contains True when the text in S is successfully converted to an Int64 value and stored i the N argument. If the conversion raises an exception, it is handled in the method and the return value is set to False. The value in N should be considered as "undefined" in this scenario.

True when the text contains a valid Int64 value.
Text converted to a numeric value in the method.
Contains the successfully converted numeric value for the string.
Converts the specified numeric value to its String representation.

ValueToStr is an overridden String function used to convert the value specified in AValue to its representation as a String data type. AValue is an Int64 type.

ValueToStr calls IntToStr to convert the integer value to the String used as the return value for the method. When ThousandSeparator has been assigned, the InsertThousandSeparator routine is called to apply the display formatting to the return value.

ValueToStr is used in the implementation of both the UpdateControl and RealGetText methods in the ancestor class.

String representation for the specified numeric value.
Numeric value converted in the method.
Amount by which the control value is increased or decreased when UpDown is clicked.

Increment is an Int64 property in TCustomSpinEditEx, and represents the amount by which the control value is increased or decreased when the UpDown button is clicked. The default value for the property is 1.

Increment is used in the implementation of the SafeInc and SafeDec methods.

Contains the thousands separator used to format and display the control value.

ThousandSeparator is a String property which contains the character used as the thousands separator in the control. It is implemented as a String type to allow use of UTF-8-encoded characters in the property value. When it is unassigned (contains an empty string), the separator is not used to format the string value for the control.

Changing the value in ThousandSeparator causes the UpdateControl method to be called to update the display for the control.

ThousandSeparator is used in methods like EditKeyPress, TextIsNumber, and ValueToStr.

Implements a spin edit control for an Int64 data type.

TSpinEditEx is a TCustomSpinEditEx descendant which implements a spin edit control using an Int64 value. TSpinEditEx sets the visibility for properties defined in ancestor classes.

Use the ThousandSeparator to set the UTF-8-encoded value used as the decimal point in the control value.

Set Increment to the value by which the control is increased or decreased when the UpDown button is clicked.

Use ValueToStr to get the string representation for the numeric value.

Gets debugging information about a value from TNullValueBehaviour.

DbgS is an overloaded String function used to get information displayed in the Debugger. This variant of the routine accepts a TNullValueBehaviour argument, an converts the specified value to its string representation,

String representation for the specified null value behavior.
Enumeration value converted to a string in the method.
Introduction to Extended Spin Edit Controls.

The SpinEx.pp unit contains extended spin edit controls, like TSpinEditEx and TFloatSpinEditEx. They are very similar to TSpinEdit and TFloatSpinEdit, but provide additional features which allow a NullValue for the control and behaviors performed when the value for the control is not a valid numeric value.

This introduction will discuss the problems the design of the controls, and the problems they are intended to eliminate.

Why another SpinEdit or FloatSpinEdit control?

The standard controls, TSpinEdit and TFloatSpinEdit, do not support a NullValue mechanism. Also, their implementations are widgetset dependent. While this provides a control that has the look and feel native to the widgetset, the behavior also depends on the widgetset. This is especially important when the text for the control contains an invalid numeric value (otherwise not a number). In such a case, when querying the control for it's Value, the results are not consistent for the various platforms. The difference in behavior between widgetsets also prevents implementation of the NullValue mechanism, especially the possibility to leave the control empty or to display informative text inside the control about the condition.

TSpinEditEx handles Int64 values, while TSpinEdit is limited to LongInt values. This is because TSpinEdit inherits from TCustomFloatSpinEdit and the internal member for the Value is stored using the Double type, and Double does not have enough significant digits to handle the range for the Int64 type.

In addition, TFloatSpinEditEx can set the value for its DecimalSeparator property independent of the value in the DefaultFormatSettings for the platform or operating system. Note: Unlike T(Float)SpinEdit, the GetValue method is always derived from the actual text in the control. This is by design, and it should not be altered.

Why not simply associate a TUpDown with a TEdit instead?

Using TEdit with a TUpDown control has several disadvantages:

- It does not allow floating point values.
- Its range is limited to the range for the SmallInt type.
- It does not properly anchor and/or align.

While both TSpinEditEx and TFloatSpinEditEx use a TUpDown control in their implementations, they do not use the Associate property in TUpDown. The two controls (the edit and the up/down button) are embedded in a TCustomControl (much like TEditButton) to provide proper alignment and anchoring behavior.