From 77576dbbf1694a2eed67c8451f01240e517b02c4 Mon Sep 17 00:00:00 2001 From: dsiders Date: Mon, 13 Jan 2025 02:15:42 -0500 Subject: [PATCH] Docs: LazControls/laznumedit. Updates content in TLazIntegerEditGen topics. Revises topic links in TLazIntegerEdit. --- components/lazcontrols/docs/laznumedit.xml | 901 ++++++++++++++++++--- 1 file changed, 769 insertions(+), 132 deletions(-) diff --git a/components/lazcontrols/docs/laznumedit.xml b/components/lazcontrols/docs/laznumedit.xml index 1a936e03eb..ffcc538d8e 100644 --- a/components/lazcontrols/docs/laznumedit.xml +++ b/components/lazcontrols/docs/laznumedit.xml @@ -1,17 +1,15 @@ - - + - -Implements an edit control specialized for Integer values with a specific -numeric base (radix). +Implements an edit control specialized for Integer values which can be +displayed with a specific numeric base (radix). @@ -63,6 +61,13 @@ Optional prefix for the new numeric base. + + +Generic type. makeskel generated it... so it is included here. It doesn't +appear to be used at all. + + + Defines the base class for an Integer edit control using a specified numeric @@ -197,10 +202,47 @@ Upper limit for the Int64 value in the control. -Implements an alternate KeyDown method used in the control. +Implements an alternate KeyDown method for the generic base class. - - + +

+_KeyDown is an implementation of the KeyDown method specific to the generic +base class. It allows an alternate implementation without use of the override +directive - which is not allowed in the generic class. +

+

+Key contains the virtual key code examined in the method. Shift contains the +Alt, Ctrl, Shift, or Meta modifiers for the virtual key code. +

+

+_KeyDown calls the KeyDown method in the ancestor class on entry to signal an +assigned OnKeyDown event handler, or any control handlers using the +chtOnKeyDown handler type. +

+

+_KeyDown ensures that the following key codes are applied to the Text for the +edit control: +

+
    +
  • VK_BACK
    • +
  • VK_DELETE
    • +
+

+For both key codes, a visible sign (+ or -) or prefix for the DisplayBase in +use on the the control is preserved. +

+

+_KeyDown is called from the overridden KeyDown method in the TLazIntegerEdit +descendant. +

+ + + +TWinControl.KeyDown +TWinControl.OnKeyDown +TControl.DoCallKeyEventHandler +TControlHandlerType + @@ -217,12 +259,123 @@ Shift, Ctrl, Alt, or Meta modifier(s) for the key code. Implements an alternate KeyPress method used in the control. - - + +

+_KeyPress is an implementation of the KeyPress method specific to the generic +base class. It allows an alternate implementation without use of the override +directive - which is not allowed in the generic class. +

+

+Key contains the character examined in the method. +

+

+_KeyPress calls the KeyPress method in the ancestor class on entry to signal +an assigned OnKeyPress event handler. +

+

+_KeyDown ensures that the value in Key is not one of the allowed control +characters used in the control, including: +

+
    +
  • #8 (Backspace)
    • +
  • #9 (Tab)
    • +
  • ^A (Line Feed)
    • +
  • ^C (Carriage Return)
    • +
  • ^Z (Undo)
    • +
+

+No actions are performed in the method if Key contains one of these values. +

+

+_KeyPress ensures that other characters or control characters in Key are +properly applied to the Text in the control, including: +

+
+
'-'
+
+Toggles the sign when AllowMinus is enabled, and re-selects the Text displayed +for the control. +
+
'+'
+
+Toggles the sign when AllowPlus is enabled, and re-selects the Text displayed +for the control. +
+
^X (Cut)
+
+Copies the selected text on the control to the clipboard and removes the +selected text from the display value for the control. +
+
^V (Insert)
+
+Copies the contents of the clipboard, converts it to the DIsplayBase in use, +and inserts the value into the Text for the control. If text is selected on +the control, only the selected text is replaced. +
+
ToggleBinKeys
+
+If Key contains one of he values in ToggleBinKeys, DisplayBase is toggled +between 2 (Binary) and 10 (Decimal). +
+
ToggleOctKeys
+
+If Key contains one of he values in ToggleOctKeys, DisplayBase is toggled +between 8 (Octal) and 10 (Decimal). +
+
ToggleHexKeys
+
+If Key contains one of he values in ToggleHexKeys, DisplayBase is toggled +between 16 (Hexadecimal) and 10 (Decimal). +
+
SetDecimalKeys
+
+If Key contains one of he values in SetDecimalKeys, DisplayBase is switched +to 10 (Decimal). +
+
SetBinKeys
+
+If Key contains one of he values in SetBinKeys, DisplayBase is switched to 2 ( +Binary). +
+
SetOctKeys
+
+If Key contains one of he values in SetOctKeys, DisplayBase is switched to 8 ( +Octal). +
+
SetHexKeys
+
+If Key contains one of he values in SetHexKeys, DisplayBase is switched to 16 ( +Hexadecimal). +
+
+

+Key is set to #0 if it is handled in the method. +

+

+_KeyPress is called from the overridden KeyPress method in the TLazIntegerEdit +descendant. +

+ + + + + + + + + + + + + +TWinControl.KeyPress +TWinControl.OnKeyPress + -Character value for the key press notification. +Character value for the key press notification. Set to #0 when handled in the +method. @@ -230,12 +383,34 @@ Character value for the key press notification. Implements an alternate UTF8KeyPress method used in the control. - - + +

+_Utf8KeyPress is an implementation of the Utf8KeyPress method specific to the +generic base class. It allows an alternate implementation without use of the +override directive - which is not allowed in the generic class. +

+

+_Utf8KeyPress calls the Utf8KeyPress method from the ancestor class on entry +to signal an assigned OnUtf8KeyPress event handler for the class instance. The +handler inspects the value in UTF8Key to determine whether it can be applied +to the control. Any bytes values in UTF8Key not handled in the ancestor method +are discarded. Essentially, this limits the input value for the control to the +single byte characters in the UTF-8 encoding. +

+

+_Utf8KeyPress is called from the UTF8KeyPress method in the TLazIntegerEdit +descendant. +

+ + + +TCustomEdit.OnUTF8KeyPress +TCustomEdit.OnUTF8KeyPress + -UTF-8 character value for the key press notification. +UTF-8-encoded character value for the key press notification. @@ -249,7 +424,8 @@ Implements an alternate InitializeWnd method used in the control. -Implements an alternate RealGetText method used in the control. +Implements an alternate RealGetText method used to get the text for the +control. @@ -288,29 +464,63 @@ Implements an alternate EditingDone method used in the control. Implements an initialization routine used for new instances of the control. - - + +

+_Init acts as a constructor for instances of the generic base class. It is +called from the constructor in TLazIntegerEdit to ensure that default values +are assigned to members, including: +

+
    +
  • MinValue (Low(Int64))
    • +
  • MaxValue (High(Int64))
    • +
  • DisplayBase (10)
    • +
  • BinIndicator ('%')
    • +
  • HexIndicator ('$')
    • +
  • OctIndicator ('&')
    • +
  • SetDecimalKeys ('#')
    • +
  • ToggleBinKeys ('%')
    • +
  • ToggleHexKeys ('$x')
    • +
  • ToggleOctKeys ('&)
    • +
  • AllowMinus (True)
    • +
  • AllowPlus (True)
    • +
+ + + + + + + + + + + + + + + + -Value for the control as an Int64 type. +Value for the control as an Int64 type.

Value is an Int64 property which contains the decimal -(base-10) value for the control. Changing the property value causes the display -Text in the control to be updated and redisplayed. DisplayBase determines the -numeric base (radix) for the converted control Value. An optional prefix is -used for numeric base values in DisplayBase like base-2 (binary), base-8 -(octal), and base-16 (hexadecimal). +(base-10) value for the control. Changing the property value causes the +display Text in the control to be updated and displayed. DisplayBase +determines the numeric base (radix) for the converted control Value. An +optional prefix is used for numeric base values in DisplayBase like base-2 +(binary), base-8 (octal), and base-16 (hexadecimal).

Use MinValue and MaxValue to set lower and upper limits for the control Value. -Changing the property causes the new value to be normalized for the limits in -MinValue and MaxValue; if the new value is not in the specified range, it is -changed to the corresponding lower or upper limit. +Changing the Value property causes the new value to be normalized for the +limits in MinValue and MaxValue; if the new value is not in the specified +range, it is changed to the corresponding lower or upper limit.

@@ -333,11 +543,11 @@ CurrentValue is a read-only Int64 property which contains the control value while editing is active and before the control loses focus. The property value is derived by reading the Text in the edit box and converting it from the selected DisplayBase back to a decimal (base-10) value. If a handle has not -been allocated for the contro, the Value property is used instead. +been allocated for the control, the Value property is used instead.

-Use Valid to determine if the edit box contains a valid value for the specified -DisplayBase. +Use Valid to determine if the edit box contains a valid value for the +specified DisplayBase.

@@ -351,9 +561,18 @@ DisplayBase. Indicates whether the value in the CurrentValue property is valid for the -selected DisplayBase. +setting in DisplayBase. - + +

+Valid is a read-only Boolean property which indicates whether the text +displayed on the control is a valid numeric value for the setting in +DisplayBase. Valid converts the edit text to an Int64 value, and checks +whether the value is within the limits specified in MinValue and MaxValue. +This includes comparing the prefix in the edit text (if any) to the prefix +needed for the DisplayBase setting. +

+ @@ -362,23 +581,67 @@ selected DisplayBase. -Contains the lower limit for the Value property. +Sets the lower limit for the Value property. - + +

+MinValue is an Int64 property which specifies the smallest Base-10 (decimal) +value allowed for the control. Changing the value in MinValue causes any +existing text on the edit control to be converted back to decimal (if needed) +and normalized to the limits specified in MinValue and MinValue. +

+

+The default value for the property is set in the _Init method to the value in +the Min_Limit constant. +

+

+Use MaxValue to specify the largest Base-10 Value allowed for the control. +

+

+MinValue and MaxValue are used when the Value property is updated, and ensure +that the limits for the control are applied to Value before the display text +is converted / displayed for the specified DisplayBase. +

+ - + + + + -Contains the upper limit for the Value property. +Sets the upper limit for the Value property. - + +

+MaxValue is an Int64 property which specifies the largest Base-10 (decimal) +value allowed for the control. Changing the value in MaxValue causes any +existing text on the edit control to be converted back to decimal (if needed) +and normalized to the limits specified in MinValue and MinValue. +

+

+The default value for the property is set in the _Init method to the value in +the Max_Limit constant. +

+

+Use MinValue to specify the smallest Base-10 Value allowed for the control. +

+

+MinValue and MaxValue are used when the Value property is updated, and ensure +that the limits for the control are applied to Value before the display text +is converted / displayed for the specified DisplayBase. +

+ - + + + + @@ -388,22 +651,23 @@ Contains the numeric base (radix) for the value displayed in the control.

-DisplayBase is an Integer property which contains the numeric base (or radix) for the value displayed and maintained in the edit control. +DisplayBase is an Integer property which contains the numeric base (or radix) +for the value displayed and maintained in the edit control.

-DisplayBase determines the number of digits used to represent the Value in the -control and controls the conversion performed to get the display value. The -default value for the property is 10 and indicates the control displays its -Value using base-10 or decimal notation. +DisplayBase determines the number of digits needed to represent the base-n +text displayed on the control, and controls the conversion performed to get +the display value. The default value for the property is 10 and indicates that +the control displays its Value using base-10 or decimal notation.

DisplayBase must be in the range 2..35; a value outside this range is normalized to the lower or upper limit.

-Changing the value for the property causes the OnBaseChange event handler to be -signalled (when assigned) using the old and new values for the property and the -optional prefix for the new numeric base (radix). +Changing the value for the property causes the OnBaseChange event handler to +be signalled (when assigned) using the old and new values for the property and +the optional prefix for the new numeric base (radix).

The Text for control is updated by converting Value to the specified radix and @@ -412,61 +676,182 @@ HexIndicator for more information about common prefixes used for selected DisplayBase values.

- + + + + + + + -Contains the characters or keys which can be applied to the edit control for a -value using the decimal (base-10) radix. +Contains the characters which cause the edit control to be displayed using the +decimal (base-10) radix. - - + +

+SetDecimalKeys is a String property which contains the character(s) used to +switch the edit controls to the decimal (base-10) radix when a key press is +handled for the control. SetDecimals is used in the _KeyPress handler, and +causes the DisplayBase property to be set to 10. +

+

+The default value for the property is '#' as assigned in the _Init method. +

+ +Please note that SetDecimalKeys is not like the toggles in the ToggleBinKeys, +ToggleOctKeys, and ToggleHexKeys properties. It does not toggle between +base-10 and another radix value. It selects base-10 only. + + + + + + + + + + -Contains the prefix used for a control value displayed in hexadecimal format -(DisplayBase = 16). +Contains the prefix displayed in the control when the value is displayed in +hexadecimal representation (DisplayBase = 16). - - + +

+HexIndicator contains the prefix displayed in the edit control when +DisplayBase is set to 16 for hexadecimal format. The default value for the +property is '$' as assigned in the _Init method. Changing the value for the +property causes the text displayed on the control to be converted and +re-encoded when DisplayBase is 16. +

+

+Use BinIndicator or OctIndicator for the prefix used for base-2 and base-8 +respectively. +

+ + + + + + + -Contains the characters or keys which can be applied to the edit control for a -value using the hexadecimal (base-16) radix. +Contains the character(s) which cause the edit control to be displayed using +the hexadecimal (base-16) radix. - - + +

+A default value is not assigned for the property. The ToggleHexKeys property +is used to toggle between Hexadecimal (base-16) and Decimal (base-10). When a +value is assigned to ToggleHexKeys, those keys take precedence over the keys +in SetHexKey. The value in SetHexKeys is used, when applicable, in the +_KeyPress handler for the control. +

+ + + + + + -Contains key(s) which cause the DisplayBase to be toggled between decimal (10) -and hexadecimal (16) display formats. +Contains key(s) which cause the DisplayBase to be toggled between decimal +(base-10) and hexadecimal (base-16) display formats. - - + +

+ToggleHexKeys is a String property which contains one or more characters which +cause the DisplayBase for the control to be toggled between decimal (base-10) +and hexadecimal (base-16). The default value for the property is '$x' as +assigned in the _Init method. If either of the keys is entered when the +control has focus, the DisplayBase property is updated accordingly and the +display Text for the control is updated to to reflect the numeric +representation using the radix. +

+

+Values in ToggleHexKeys are used in the _KeyPress method when a key value is +applied to the edit control. +

+

+Use ToggleBinKeys or ToggleOctKeys to specify the key characters which cause +the control to toggle between Binary or Octal, and Decimal representations for +the control Value. +

+

+Use SetDecimalKeys, SetBinKeys, SetOctKeys, or SetHexKeys to switch to a +specific base-n representation rather than toggle between a base-n +representation and decimal (base-10). +

+ + + + + + + + + + + + + -Contains the prefix used for a control value displayed in octal format -(DisplayBase = 8). +Contains the prefix displayed in the control when the value is displayed in +octal representation (DisplayBase = 8). - - + +

+OctIndicator contains the prefix displayed in the edit control when +DisplayBase is set to 8 for octal format. The default value for the +property is '&' as assigned in the _Init method. Changing the value for +the property causes the text displayed on the control to be converted and +re-encoded when DisplayBase is 8. +

+

+Use BinIndicator or HexIndicator for the prefix used for base-2 and base-16 +respectively. +

+ + + + + + + -Contains the characters or keys which can be applied to the edit control for a -value using the octal (base-8) radix. +Contains the character(s) which cause the edit control to be displayed using +the octal (base-8) radix. - - + +

+A default value is not assigned for the property. The ToggleOctKeys property +is used to toggle between Hexadecimal (base-16) and Decimal (base-10). When a +value is assigned to ToggleHexKeys, those keys take precedence over the keys +in SetOctKeys. The value in SetOctKeys is used, when applicable, in the +_KeyPress handler for the control. +

+ + + + + + @@ -474,26 +859,90 @@ value using the octal (base-8) radix. Contains key(s) which cause the DisplayBase to be toggled between decimal (10) and octal (8) display formats. - - + +

+ToggleOctKeys is a String property which contains one or more characters which +cause the DisplayBase for the control to be toggled between decimal (base-10) +and octal (base-8). The default value for the property is '&' as +assigned in the _Init method. If the key is entered when the control has +focus, the DisplayBase property is updated accordingly and the display Text +for the control is updated to to reflect the numeric representation using the +radix. +

+

+Values in ToggleOctKeys are used in the _KeyPress method when a key value is +applied to the edit control. +

+

+Use ToggleBinKeys or ToggleHexKeys to specify the key characters which cause +the control to toggle between Binary or Hexadecimal, and Decimal +representations for the control Value. +

+

+Use SetDecimalKeys, SetBinKeys, SetOctKeys, or SetHexKeys to switch to a +specific base-n representation rather than toggle between a base-n +representation and decimal (base-10). +

+ + + + + + + + + + + + + -Contains the prefix used for a control value displayed in binary format -(DisplayBase = 2). +Contains the prefix displayed in the control when the value is displayed in +binary representation (DisplayBase = 2). - - + +

+BinIndicator contains the prefix displayed in the edit control when +DisplayBase is set to 2 for octal format. The default value for the property +is '%' as assigned in the _Init method. Changing the value for the property +causes the text displayed on the control to be converted and re-encoded when +DisplayBase is 2. +

+

+Use OctIndicator or HexIndicator for the prefix used for base-8 and base-16 +respectively. +

+ + + + + + + -Contains the characters or keys which can be applied to the edit control for a -value using the binary (base-2) radix. +Contains the character(s) which cause the edit control to be displayed using +the binary (base-2) radix. - - + +

+A default value is not assigned for the property. The ToggleBinKeys property +is used to toggle between Binary (base-2) and Decimal (base-10). When a +value is assigned to ToggleBinKeys, those keys take precedence over the keys +in SetBinKeys. The value in SetBinKeys is used, when applicable, in the +_KeyPress handler for the control. +

+ + + + + + @@ -501,8 +950,42 @@ value using the binary (base-2) radix. Contains key(s) which cause the DisplayBase to be toggled between decimal (10) and binary (2) display formats. - - + +

+ToggleBinKeys is a String property which contains one or more characters which +cause the DisplayBase for the control to be toggled between decimal (base-10) +and binary (base-2). The default value for the property is '%' as assigned in +the _Init method. If the key is entered when the control has focus, the +DisplayBase property is updated accordingly and the display Text for the +control is updated to to reflect the numeric representation using the radix. +

+

+Values in ToggleBinKeys are used in the _KeyPress method when a key value is +applied to the edit control. +

+

+Use ToggleOctKeys or ToggleHexKeys to specify the key characters which cause +the control to toggle between Octal or Hexadecimal, and Decimal +representations for the control Value. +

+

+Use SetDecimalKeys, SetBinKeys, SetOctKeys, or SetHexKeys to switch to a +specific base-n representation rather than toggle between a base-n +representation and decimal (base-10). +

+ + + + + + + + + + + + + @@ -522,35 +1005,98 @@ See TLazIntegerEditBaseChangeEvent for more information about the handler type and its arguments.

-OnBaseChange is a public property and does not appear in the Object -Inspector at design-time; it must be assigned at run-time using an object -procedure which implements the signature for the event. +OnBaseChange is a public property in TLazIntegerEditGen, but it is published +in the TLazIntegerEdit descendant.

+ -Indicates whether the '-' key can be used when editing the control value. +Indicates whether the '-' key can be used to negate the control Value. - - + +

+AllowMinus is a Boolean property which enables or disables use of the '-' key +to change the sign for the value in the control. When enabled, the +CurrentValue for the control is negated when the '-' key is pressed. A second +press of the key causes the CurrentValue to become positive. The default value +for the AllowMinus property is True. AllowMinus does enable direct +entry of the sign; it reverses its state. +

+

+When editing is completed in the control, or it loses focus, the CurrentValue +for the control is validated using the MinValue and MaxValue properties. If +MinValue is not set to a value less than 0 (zero), a negative Value cannot be +stored for the control and it defaults to MinValue. +

+

+AllowMinus and AllowPlus are used when key press events are applied in the +_KeyPress handler. +

+

+Use AllowPlus to enable or disable use of the '+' key to force the control +Value to become positive. +

+ + + + + + + + + + -Indicates whether the '+' key can be used when editing the control value. +Indicates whether the '+' key can be used to switch a negative control value +to a positive one. - - + +

+AllowPlus is a Boolean property which enables or disables use of the '+' key +to change the sign for the Value in the control to a positive one. When +enabled, the CurrentValue for the control is negated when the '+' key is +pressed. and the control value is negative. No actions are performed if the +CurrentValue is already positive. AllowPlus does enable direct entry of the +sign; it simply forces a positive sign for the value. +

+

+When editing is completed in the control, or it loses focus, the CurrentValue +for the control is validated using the MinValue and MaxValue properties. +

+

+AllowMinus and AllowPlus are used when key press events are applied in the +_KeyPress handler. +

+

+Use AllowMinus to enable or disable use of the '-' key to toggle the sign for +the control Value. +

+ + + + + + + + + + Handles UTF-8-encoded key press events for the control. @@ -741,6 +1290,8 @@ control. - + - + - + - + - + - + + +Contains the prefix displayed in the control when the value is displayed in hexadecimal format (DisplayBase = 16). + + +

+HexIndicator contains the prefix displayed in the edit control when +DisplayBase is set to 16 for hexadecimal format. The default value for the +property is '$' as assigned in the _Init method in the base class. Changing +the value for the property causes the text displayed on the control to be +converted and re-encoded when DisplayBase is 16. +

+

+Use BinIndicator or OctIndicator for the prefix used for base-2 and base-8 +respectively. +

+ + + + + + + + + - + + +Contains the character(s) which cause the edit control to be displayed using +the hexadecimal (base-16) radix. + + +

+A default value is not assigned for the property. The ToggleHexKeys property +is used to toggle between Hexadecimal (base-16) and Decimal (base-10) +instead. When a value is assigned to ToggleHexKeys, those keys take precedence +over the keys in SetHexKey. The value is used, when applicable, in the +_KeyPress handler for the control. +

+ + + + + + + + - + + + - + - + - + - + - + - + - + - + - + + - + - + + + - - - - - - - + + + + + + + + + + + + + + + @@ -864,7 +1501,7 @@ Owner of the class instance. - +