This unit contains classes for spin edit controls.

spin.pp contains classes which implement spin edit controls. This file is part of the Lazarus Component Library (LCL).

The following components are added to the Lazarus IDE component palette:

Misc Tab

- TSpinEdit
- TFloatSpinEdit

Original author: Shane Miller.

The base class for the float-based spin control.

TCustomFloatSpinEdit is a TCustomEdit descendant which implements the base class for the float-based spin edit control. It provides an edit control where the Float value can be entered directly, and up / down buttons which can be used to increment or decrement the value for the control.

Use the MinValue and MaxValue properties to define the lower and upper limits for the value in the control.

Use the Increment property to set the value added to or subtracted from the control value when the up or down buttons are clicked.

Default increment for the control.
Default decimal places displayed for the control.
Default value for the MaxValue property.
Stores the increment for the control.
Stores the decimal places displayed for the control.
Stores the value for the EditorEnabled property.
Stores the value for the MaxValue property.
Stores the value for the MinValue property.
Internal flag which controls the value for Modified in the OnChange event handler.
Stores the value for the Value property.
Stores the value for the ValueEmpty property.
Internal flag used in the control.
Internal flag used in the control.
Gets the value for the Value property.
Value for the property.
Sets the value for the EditorEnabled property.
New value for the property.
Normalizes the Value for the control and notifies the widgetset class.
Implements the storage specifier for the MaxValue property.
True if an explicit value has been assigned to MaxValue.
Implements the storage specifier for the Increment property.
True if an explicit value has been assigned to Increment.
Updates Modified prior to sending control messages and signalling OnChange handler(s).

Change is an overridden method in TCustomFloatSpinEdit. It ensures that the value in Modified is updated when the widgetset class applies a new value for the control. An internal flag is used to determine if Modified is set to False prior to calling the inherited Change method. The flag is set when a new value is applied to the Value property in program code (instead of using the UI elements for the control). This is performed here because the widgetset class calls Changed and not TextChanged.

Change calls the inherited method where the CM_CHANGED control message is posted, and assigned OnChange handlers are signalled for the control.

TCustomEdit.Modified TCustomEdit.Change
Performs actions when editing has been completed for the control.

EditingDone is an overridden method in TCustomFloatSpinEdit. It ensures that the control is updated when editing has been completed.

EditingDone calls the UpdateControl method to normalize and validate the control Value using the assigned range in MinValue and MaxValue. This includes calling GetLimitedValue to update the control Value when both MinValue and MaxValue contain a valid range. The value in the widgetset class is updated when component streaming is not active, and the control is not being freed.

EditingDone calls the inherited method to signal the OnEditingDone event handler (when assigned) when ReadOnly is False.

EditingDone is called from the KeyUpAfterInterface method in TCustomEdit when the Enter (VK_RETURN) key code is handled for the control. It also occurs when the focused control has been changed.

The method override was added in LCL version 2.2.1.
TCustomEdit.EditingDone TControl.OnEditingDone
Gets the value for the text in the control.

RealGetText is an overridden method in TCustomFloatSpinEdit, and calls the inherited method to get the return value when the Handle has been allocated for the control. If the Handle has not been assigned, ValueToStr is called to get the return value for the method.

TCustomEdit.RealGetText
Updates the control state when the value in Text has been changed.

TextChanged is an overridden method in TCustomFloatSpinEdit. It ensures that internal flags are updated to track the value and state for the control when it has been changed. It calls the inherited method to validate the content in Text and update the caret position for the control.

TCustomEdit.TextChanged TCustomEdit.CaretPos
Sets the value for the DecimalPlaces property.
New value for the DecimalPlaces property.
Sets the value for the Value 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 ValueEmpty property.
New value for the property.
Sets the value for the Increment property.
New value for the property.
Creates or re-creates the handle for the windowed control.
TCustomEdit.InitializeWnd
Frees the handle for the windowed control.
TWinControl.FinalizeWnd
Performs actions when LCL component streaming is completed.

Loaded calls the inherited method on entry to determine the size for the control (and its children) and to apply property values inherited from the parent control (when assigned). Loaded calls the private UpdateControl method when the internal update flag has been set for the control.

TWinControl.Loaded
Handles key press events for the control.

KeyPress is an overridden method used to handle key press events for the control. KeyPress calls the inherited method on entry. If the character in Key is not handled in the ancestor class, the argument is examined to determine if it is valid for the control. If Key is not a valid character, it is set to #0 to ignore the key press event.

KeyPress disallows any value in Key that is not a numeric digit, sign character ('+' or '-'), or decimal point character ('.' or ','). The decimal point is automatically converted to the value used in the DefaultFormatSettings variable from the RTL. The decimal point is not allowed when Decimals is set to 0 (zero).

KeyPress does not ensure that the value in Key is valid for a specific position in the control value. It does not guarantee that sign indicators are used only at the start of the control value. Nor does it guarantee that a decimal point character is not used more than once in the entered value. This is implemented in a manner that is Delphi compatible.

Tab (#9), BackSpace (#8), Cut (^X), Paste (^V), Copy (^C), and Undo (^Z) characters are allowed in Key so that they may be applied in inherited methods for the control.

Character value for the key press event.
Gets the default size for new instances of the class.
Default size for the new class instance.
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited method on entry. Create sets the style flags needed for the spin edit control, and sets the default values for properties in the class instance. The GetControlClassDefaultSize method is called and the return value is used to set the initial size for the control.

Owner of the class instance.
Limits the specified value to the minimum and maximum values for the control.

The return value is set to AValue and limited to the range in the MinValue and MaxValue properties. This occurs when MaxValue has a value that is larger than MinValue. No constraints are applied when MinValue and MaxValue have the the same value, or when MaxValue is smaller than MinValue.

Delphi does not constrain the value when MinValue and MaxValue are the same, but does if MaxValue is smaller than MinValue.

Called from the UpdateControl, StrToValue, and ValueToStr methods.

Value for the control limited to the range in MinValue and MaxValue.
Value examined in the method.
Converts the specified value to a String type using the spin edit settings.

Calls GetLimitedValue to range limit the value in AValue. Calls FloatToStrF to format the return value using 20 digits of precision and the number of decimals in the DecimalPlaces property.

String representation for the float value.
Float value converted to a string in the method.
Converts the specified string to a float value according to spin edit settings.

Calls StrToFloatF to convert the value in S to a Double data type. If S contains an invalid representation for a float value, Value is used as the return value for the method.

Float value for the specified string.
String examined and converted to a float value in the method.
Number of the decimal places displayed in the spin edit control.

DecimalPlaces is used in the ValueToStr method, and determines the decimal precision for the value displayed in the spin edit control.

Indicates whether the value for the control can be entered directly into its edit box.

EditorEnabled is a Boolean property which indicates if the Value for the control can be input directly. When set to True, the edit box is enabled. When set To False, only the up and down arrow buttons can be used to change the Value for the control.

The default value for the property is True. Changing the value for the property causes the widgetset class to be notified when the Handle for the control has been allocated.

EditorEnabled is independent of the settings in the ReadOnly and Enabled properties. When ReadOnly is set to True, the Value for the control cannot be modified using either the edit box or the up / down buttons. When Enabled is set to False, the control cannot be given focus or modified.

Disabling the edit box requires support from the underlying widgetset class. It may not be supported or implemented for all widgetsets / platforms. In the current LCL version, it is implemented for the Windows and Windows CE platforms.
Added in LCL version 2.1.
Amount applied to the control value when the up or down arrow button is pushed.

The default value for the property is defined in the DefIncrement constant (1). Changing the value for the property causes the UpdateControl method to be called.

Minimal value allowed for the spin edit control.

Minimal value allowed for the spin edit control. Set the MinValue property equal to MaxValue to allow any number to be selected.

Maximal value allowed for the spin edit control.

Maximal value allowed for the spin edit control. Set the MinValue property equal to MaxValue to allow any number to be selected.

The value for the spin edit control.

Value is a Double property which contains the value for the spin edit control. Its content can be modified using the UI elements for the control (up and down buttons, up and down cursor keys, edit box for the control). It can also be directly assigned in program code.

Changing the value for the property causes the Text for the control to be checked for a valid numeric representation in the property. If the new property value is the same as the existing value, no actions are performed.

When the property value has been stored, internal flags are set to ensure that Modified is updated accordingly and the private UpdateControl method is called. If the handle for the control has been allocated, the Change method is called to post a CM_CHANGED control message and signal OnChange handler(s) assigned for the control.

Value is constrained to the range defined in the MinValue and MaxValue properties.

TCustomEdit.Modified
Indicates if a value has not been assigned for the control.
ValueEmpty
is updated in the TextChanged method when a new value has been assigned to the control. Changing the value for the property causes the UpdateControl method to be called.
Implements a float-based spin edit control.

TFloatSpinEdit is a TCustomFloatSpinEdit descendant which implements a spin edit control for a Float value. It provides an edit control for the numeric value and up / down buttons that can be clicked to increment or decrement the Value for the control. TFloatSpinEdit sets the visibility for properties introduced in ancestor classes.

Use TSpinEdit to edit an Integer value.

Indicates whether the selected content in the control has been automatically selected.

AutoSelected is updated in methods which handle focus change actions for the control, including: MouseDown, MouseUp, DoEnter, and DoExit. In general, it indicates when the Text and SelText properties have the same value.

The visibility for the property is public, and does not appear in the Object Inspector at design-time. It is, however, available in code at run-time. It is not declared as a read-only property, but there is no obvious reason to assign a value that does not result from calling the SelectAll method.

Use AutoSelect to control whether auto-selection is enabled for the control.

TCustomEdit.AutoSelected
The OnChange event is fired when spin edit value has changed.

OnChange event is similar to TCustomEdit.OnChange, and is signalled for changes made by the user and for changes made in code. A change is a modification which will cause the text displayed on the screen by the control to be altered. This corresponds to a change in the Value property for the control. The event is called after the change takes place, so Value will already have the new property value.

TCustomEdit.OnChange TSpinEdit.OnChange
The base class for an integer-based spin edit control.

TCustomSpinEdit is a TCustomFloatSpinEdit descendant which implements a control used to edit, increment, and decrement an Integer value. It has arrow buttons to allow the user to increment / decrement the value and an edit box used to enter a value directly.

Properties like Value, MinValue, MaxValue, and Increment are re-declared as an Integer type. It provides overridden or overloaded methods which use the Integer values needed for the implementation.

Gets the value for the Increment property.
Value for the property.
Gets the value for the MaxValue property.
Value for the property.
Gets the value for the MinValue property.
Value for the property.
Gets the value for the Value property.
Value for the property.
Sets the value for the Increment 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 Value property.
New value for the property.
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry. Create ensures that DecimalPlaces is set to 0 (zero) for the Integer type used in the Value property.

Owner of the class instance.
Gets the value for the control limited the range in MinValue and MaxValue.
GetLimitedValue
is implemented to return a Double value. This remains because the method is called from widgetset classes for both TFloatSpinEdit and TSpinEdit, and the method signature cannot be changed to use the Integer type desired for the implementation.

Calls the inherited method on entry. GetLimitedValue also ensures that the return value is valid for the MinInt and MaxInt constants defined in RTL for the platform / CPU architecture.

MaxInt
Range-limited value for the control.
Value normalized to the range in MinValue and MaxValue.
The value for the spin edit control.
Minimal value allowed for the spin edit control.

Minimal value allowed for the spin edit. Set the MinValue property equal to MaxValue to allow any number to be selected.

Maximal value allowed for the spin edit control.

Maximal value allowed for the spin edit. Set the MinValue property equal to MaxValue to allow any number to be selected.

The value by which the value of the control should be increased/decreased when the user clicks one of the arrows or one of the keyboard up/down arrows.
Implements an integer-based spin edit control.

TSpinEdit is a TCustomSpinEdit descendant which implements an integer-based spin edit control. It provides an edit control where the Integer value can be entered directly, and has arrow buttons to allow the user to increment / decrement the value for the control.

TSpinEdit sets the visibility for properties introduced in ancestor classes.

Use TFloatSpinEdit to edit a float value in a spin edit control.

The OnChange event is fired when the spin edit value has changed.

This OnChange event is based on TCustomEdit.OnChange, so it is fired both on changes made by the user and also for changes made by code. A change is defined as a modification which will cause the text displayed on the screen by the control to change. This corresponds to a change in the property Value in the control. The event is called after the change takes place, so the Value property will contain the new value.

TCustomEdit.OnChange TFloatSpinEdit.OnChange
Registers components for use in the Lazarus IDE.

The following components are added to the Lazarus IDE component palette:

Misc Tab

- TSpinEdit
- TFloatSpinEdit