From a8e9f489b74e311fd21153baebc47b64c99af97d Mon Sep 17 00:00:00 2001 From: dsiders Date: Wed, 25 Oct 2023 04:40:40 +0100 Subject: [PATCH] Docs: LCL/calcform. Updates content in various topics. (cherry picked from commit 586323470e06990be4a9382d9be6c0636bb65999) --- docs/xml/lcl/calcform.xml | 446 +++++++++++++++++++++++++++++++------- 1 file changed, 368 insertions(+), 78 deletions(-) diff --git a/docs/xml/lcl/calcform.xml b/docs/xml/lcl/calcform.xml index 059f9ee614..506c5c4b13 100644 --- a/docs/xml/lcl/calcform.xml +++ b/docs/xml/lcl/calcform.xml @@ -62,7 +62,9 @@ changed. - + +Represents status values used in TCalculatorPanel. +

TCalculatorState is an enumerated type with values that represent @@ -76,19 +78,27 @@ type used to implement the Status property in -Value on the First key press. + +Value when an initial key press or button click has not yet been detected and +applied to a calculator panel. + -Value after the operation for the key has been applied successfully. +Value after an operation for a key press or mouse click has been successfully +applied. -Value when the operation resulted in an error. + +Value when an operation results in an error condition for a calculator panel. + - + +Represents layouts used for panels on a TCalculatorForm instance. +

TCalculatorLayout is an enumerated type with values that represent @@ -105,11 +115,15 @@ methods in TCalculatorForm and TCalculatorPanel. -The default layout with larger button sizes and more whitespace. +The default layout with larger button sizes, more whitespace, and buttons for +common calculator operations like Back, Clear, Ok and Cancel. -The compact layout with smaller button sizes. + +The compact layout with smaller buttons using equally sized sizes. Some buttons +like Back, Clear, Ok and Cancel are omitted in the simple layout. + @@ -160,29 +174,56 @@ Ensures that Text is updated and displayed when Status is csFirst. -Performs actions for a key press not handled by a button in the calculator -panel. +Performs actions for a key press notification in the calculator panel. - + + + + + - + +Character value for the key pressed. + Clears the display and operator in the calculator panel. - - + +

+Called when the Clear button on the panel is clicked, or when the 'C' key is +pressed. Sets the display text to '0/0' and causes the OnDisplayChange event +handler to be notified. Resets the OperatorChar property to '='. +

+ + + + + + -Updates the calculator panel to reflect an error condition, and signals -OnError. +Updates the calculator panel to reflect an error condition and signals the +OnError event handler. - - + +

+Changes the text displayed on the panel to the value in the rsError resource +string and updates the Status property to csError. Calls ErrorBeep to produce +an error beep when enabled in BeepOnError. Signals the OnError event handler +(when assigned). +

+ + + + + + + @@ -203,7 +244,9 @@ OnDisplayChange. - + +Textual representation for DisplayValue using the Precision for the panel. + @@ -249,43 +292,104 @@ Translates a mouse click on a button to the character key used in CalcKey. - + +Produces an error tone when enabled using the BeepOnError property. + -ErrorBeep is an empty implementation in the current LCL version. +

+ErrorBeep has an empty implementation in the current LCL version. No error tone +is produced. +

 -Sets the display text for the associated control and signals OnTextChange. +Sets the display text for the calculator panel and signals OnTextChange. - + + + Initializes and configures the calculator panel using the specified layout. - - + +

+CreateLayout is a constructor for the class instance. It calls the +inherited Create constructor on entry, and sets the default values for +properties. +

+

+AOwner is the component which owns the class instance (the +TCalculatorForm instance). +

+

+ALayout specifies both the position and size for the buttons on the +panel. It affects the Width and Height for the panel as well. +

+

+CreateLayout creates the calculator buttons and positions them on the panel for +the specified layout. When clNormal is used in ALayout, buttons are created for +Back, Clear, Ok and Cancel. clNormal also causes a panel used for Memory +display to be created and positioned. +

+

+CreateLayout is called from the InitForm method in TCalculatorForm. +

+ + + + + +TCustomPanel.Create + - + +Component which owns the class instance. + - + +Layout applied to the panel and its buttons. + -Locates the button using the specified Key and perform its Click method. +Applies a key or button press to the calculator panel. -CalcKey is called when a button is located using the specified Key. +

+CalcKeyPress is a method used to implement the OnKeyPress event handler for the +TCalculatorForm instance where the panel is displayed. +

+

+Sender is the object instance (TCalculatorForm) for the event +notification. +

+

+Key is the character value for the key (or button) for the +notification. If Key is the caption for one of the buttons on the panel, its +Click method is called. Otherwise, the private CalcKey method is called to +apply the Key value. +

+

+CalcKeyPress is called by a TCalculatorForm instance when its OnKeyPress event +handler is executed. +

 - + + + +TForm.OnKeyPress +TCustomSpeedButton.Click + Object for the KeyPress event. @@ -295,48 +399,105 @@ CalcKey is called when a button is located using the specified Key. -Loads the value in Text into the Clipboard as a text value. - - +Loads the value in Text into the Clipboard as plain text. + +

+Called when the Copy context menu item for a TCalculatorForm instance is +clicked. +

+ + + + Pastes text from the Clipboard into the text display for the calculator panel. - - + +

+Called when the Paste context menu item for a TCalculatorForm instance is +clicked. +

+ + + + + -Gets the minimum number of precision digits allowable for the panel. +Gets the minimum number of precision digits allowed for the DisplayValue on +the panel. - - + +

+WorkingPrecision is an Integer function used to get the +number of decimal digits used to format the DisplayValue on the panel. The +minimum precision used for the floating point value is 2, but can be increased +by setting the value for the Precision property. +

+ + + + + - + +Number of decimal digits displayed for the floating point DisplayValue. + -Updates the Memory indicator to reflect a non-zero value in the Memory +Updates the Memory indicator to reflect a non-zero value present in the Memory property. - - + +

+Causes the character 'M' to be displayed when Memory has a non-zero value. +Otherwise, the Memory indicator is cleared. +

+ + + + + -Contains the Double value representing the Text in the panel. - - + +Contains the Double value representing the result (and Text) displayed on the +calculator panel. + + +

+DisplayValue is a Double property which contains the +result for a value entered or calculated using the calculator panel. The +property value is determined by calling StrToDouble to convert the value in +Text to a floating point value. The property value is 0.0 if Status contains +csError. +

+

+Changing the value for the property causes Text to be updated. The Double value +is formatted using the Precision needed for the panel, and the OnDisplayChange +event handler is signalled (when assigned). +

+ + + + + + + -Contains the Double value stored in the memory for the calculator. +Contains the Double value stored as the memory for the calculator panel. @@ -344,20 +505,25 @@ Contains the Double value stored in the memory for the calculator. -Maximum number of digits of precision allowed for the Double value in the -calculator. +Number of digits used after the decimal for the Double value in the calculator +panel. - + + + -Indicates if a beep occurs when an error condition is detected in the +Indicates whether a beep occurs when an error condition is detected in the calculator panel. - + + + + @@ -365,78 +531,162 @@ calculator panel. Contains the status or state for the calculator panel. +

+Status is a TCalculatorState property which indicate the +state for the calculator panel. Values from the TCalculatorState enumeration +are applied to the property when the panel is updated for key presses or mouse +clicks. +

+

+csError indicates an error condition was detected, and causes 0.0 to +be returned in the DisplayValue for the panel. +

 - + + + + + + + -Character representing the last operator entered in the calculator panel. +Character representing the last operator entered using the calculator panel. - + + + -Text representation for the Double value in the calculator. - - + +Text representation for the Double display value on the calculator panel. + + +

+Text is a read-only String property in +TCalculatorPanel with the textual representation for the +DisplayValue on the panel. It contains the text formatted using the Precision +needed for the DisplayValue. Text is updated when a new value is assigned to +DisplayValue, when CalcKeyPress is executed for the panel, or when methods for +Error or Clear buttons are called. +

+ + + + + - + +Event handler signalled when the OK button on the calculator panel has been +clicked. + - + +Event handler signalled when the Cancel button on the calculator form has been +clicked, or the form is closed using the Close window decoration or an +accelerator key. + - + +Event handler signalled when the Enter key, = or % operators are clicked on the +panel. + - + +Event handler signalled when the Error method is called for the calculator +panel. + - + +Event handler signalled when a new value has been assigned to the Text for the +panel. + - + +Event handler signalled when a key press is applied to the calculator panel. + - + +Event handler signalled following a change to the DisplayValue for the +calculator panel. + -Color for the calculator panel. - + +Background color for the calculator panel. + + +

+Color is a TColor property with the background color used +for the calculator panel. It is redefined in TCalculatorPanel to use clBtnFace +as the default value for the property. Please note to ParentColor is ultimately +set to True for the panels on a TCalculatorForm instance. +

+ -Implements the form used to display a calculator in a TCalculatorDialog. +Implements the form used to display a calculator for a TCalculatorDialog +instance. - - + +

+TCalculatorForm is a TForm descendant which implements +the form used to display a calculator. It extends the ancestor class with +properties, methods, and events needed to configure and display the form +instance with UI elements needed for either a simple (compact) or a normal +calculator layout. Use the Create constructor to control the layout for the +calculator form instance. +

+

+Use the Value property to set or get the value displayed on the calculator. +

+

+Use the OnCalcKey and OnDisplayChange event handlers to perform actions needed +when keys are pressed or the display value is changed on the form instance. +

+ + + + + +TForm + @@ -485,7 +735,9 @@ Performs actions needed to handle OnKeyPress events in the calculator form. - + +Object instance for the click notification. + @@ -503,7 +755,9 @@ Performs actions needed to handle OnKeyPress events in the calculator form. - + +Object instance for the click notification. + @@ -566,7 +820,10 @@ Performs actions needed for a key received in the calculator form. - + +TPanel instance used as a container for the display and button panels on the +calculator form. + @@ -608,11 +865,43 @@ Event handler signalled when the calculator display has been changed. -Creates and configures a new TCalculatorForm instance. - + +Creates, configures, and returns a new TCalculatorForm instance. + + +

+CreateCalculatorForm is a TCalculatorForm function used +to create and configure a new calculator form instance using the arguments +passed to the routine. +

+

+ALayout determines the number, type, position, and size for buttons +on the calculator form. It is passed as argument to the TCalculatorForm.Create +constructor used to instantiate the return value. See +TCalculatorLayout for more information on +the layout values. +

+

+AHelpContext contains the help context identifier assigned to the HelpContext +property in the form instance. +

+

+CreateCalculatorForm ensures that the form instance is scaled to the PPI +setting for the Screen, and updates Left and Top to center the form on the +Screen display area. If an exception occurs during this operation the form +instance is freed, and the return value is Nil. The exception is +re-raised to perform exception handling enabled in the application. +

+

+CreateCalculatorForm is called from methods in TCalcEdit and TCalculatorDialog +when the form instance is created for the controls. +

+ +TCalcEdit.RunDialog +TCalculatorDialog.Execute @@ -624,9 +913,10 @@ Event handler signalled when the calculator display has been changed. Layout for the calculator panel in the form instance. - - + +Help context for the newly created form instance in the return value. + @@ -678,19 +968,19 @@ Event handler signalled when the calculator display has been changed. -Font name used for buttons and displays in a calculator. +Font name used for buttons and text displays in a calculator. -Font size used for buttons and displays in a calculator. +Font size used for buttons and text displays in a calculator. -Font style used for buttons and displays in a calculator. +Font style used for buttons and text displays in a calculator.