From 6d30732ad9113134c85bc25ce79624e67deae097 Mon Sep 17 00:00:00 2001 From: dsiders Date: Thu, 19 May 2022 17:11:30 +0100 Subject: [PATCH] Docs: LCL/dialogs. Adds the PromptForFileName topic from 09584a03. * Includes general updates to TFindDialog topics. --- docs/xml/lcl/dialogs.xml | 921 +++++++++++++++++++++++++++++++-------- 1 file changed, 728 insertions(+), 193 deletions(-) diff --git a/docs/xml/lcl/dialogs.xml b/docs/xml/lcl/dialogs.xml index f5972fa42e..45ff51e4b0 100644 --- a/docs/xml/lcl/dialogs.xml +++ b/docs/xml/lcl/dialogs.xml @@ -876,7 +876,7 @@ - Enaboles multi-selection. + Enables multi-selection. @@ -1875,7 +1875,9 @@ ADialog.CustomColors.Values['ColorA'] := 'FFFF00'; - + + Raises an error if a font or style is (some how) selected that does not exist in the font dialog. + Hides the font name selection list in the dialog. @@ -1931,11 +1933,18 @@ ADialog.CustomColors.Values['ColorA'] := 'FFFF00'; TFontDialog displays selection lists for font name, size, style, and color. It can be configured to limit the available typefaces, sizes, and visual presentations using the Options, MinFontSize and MaxFontSize properties.

- When the dialog is executed, the selected font is made available in the Font property. The OnApplyClicked event handler can be used to perform actions needed when the optional Apply button is clicked in the dialog. + At run-time, TFontDialog is mapped to the native font selection dialog used for a given platform. Use Options to enable or disable features or behaviors in the dialog. Enabling an option does not mean that it is automatically available. Some options may not be supported in the native dialog for a given platform. +

+

+ When the dialog is executed, the selected font and its attributes is made available in the Font property. The OnApplyClicked event handler can be used to perform actions needed when the optional Apply button is clicked in the dialog.

+ + + + @@ -2008,7 +2017,7 @@ ADialog.CustomColors.Values['ColorA'] := 'FFFF00'; Contains the Font selected in the dialog.

- Font is a TFont property with the font selected using the dialog. The value in Font is updated in widgetset classes when the OK or Apply button is clicked during execution of the dialog. + Font is a TFont property with the font selected using the dialog. The value in Font is updated in widgetset classes when the OK or Apply button is clicked during execution of the dialog. It includes any attributes applied to font in the native font selection dialog for the platform.

Use the OnApplyClicked event handler to perform actions needed when the Apply button is enabled and clicked in the dialog. @@ -2062,6 +2071,9 @@ ADialog.CustomColors.Values['ColorA'] := 'FFFF00';

Include or Exclude values for the property prior to calling the Execute method.

+ + Enabling a value in Options does not mean that the feature or behavior is supported in the native font selection dialog for the platform. Some options may not be available on a given platform. + @@ -2111,12 +2123,19 @@ ADialog.CustomColors.Values['ColorA'] := 'FFFF00'; - A list of possible options which can be used in Find-dialogs. - A list of possible options which can be used in Find-dialogs. - + A list of possible options which can be used in Find dialogs. + +

+ TFindOption is an enumerated type with values representing options that can enabled in TFindDialog and descendants. Values from TFindOption are stored in the TFindOptions set type, and used to implement the TFindDialog.Options property. +

+ + + + + - If set the "Down" radiobutton is selected. + If set the "Down" radio button is selected. This option will be set when the user presses "Find Next" @@ -2128,7 +2147,7 @@ ADialog.CustomColors.Values['ColorA'] := 'FFFF00'; If set the "Whole word" checkbox is hidden from the Find dialog. - If set the "Up" and "Down" radiobuttons are hidden from the Find dialog. + If set the "Up" and "Down" radio buttons are hidden from the Find dialog. This flag is set when the user checks the "Match case" checkbox. @@ -2137,7 +2156,7 @@ ADialog.CustomColors.Values['ColorA'] := 'FFFF00'; If set the "Match case" checkbox is disabled in the Find dialog. - If set the "Up" and "Down" radiobuttons are disabled in the Find dialog. + If set the "Up" and "Down" radio buttons are disabled in the Find dialog. If set the "Whole word" checkbox is disabled in the Find dialog. @@ -2162,9 +2181,19 @@ ADialog.CustomColors.Values['ColorA'] := 'FFFF00'; - A set of TFindOption. - - + Set type used to store TFindOption enumeration values. + +

+ TFindOptions is a set type used to store zero (0) or more values from the TFindOption enumeration type. Adding an enumeration value to the set indicates that the option is enabled. +

+

+ TFindOptions is the type used to implement the TFindDialog.Options property. +

+ + + + + @@ -2184,98 +2213,29 @@ ADialog.CustomColors.Values['ColorA'] := 'FFFF00'; + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + @@ -2334,165 +2294,436 @@ ADialog.CustomColors.Values['ColorA'] := 'FFFF00'; - - - + + Returns the default title displayed on the dialog. + + +

+ DefaultTitle is an overridden String function in TFindDialog. It reimplements the method to return the value in the rsFind constant as the default caption or title for the dialog. The return value is assigned to the Title property in the inherited constructor for the class instance. +

+ + + + + rsFind + - + + Default title for the find dialog. + - FindClick - method for execution when the Find button is clicked. + Implements the OnClick event handler for the Find button on the dialog. - - + +

+ FindClick is a method which implements the event handler signalled when the Find button on the dialog form is clicked. +

+

+ FindClick calls GetFormValues to update Options from the settings on the internal form instance for the dialog. It also ensures that Options contains only find-related enumeration values, and not those intended for a replace dialog. +

+

+ FindClick calls Find to signal the OnFind event handler (when assigned). +

+

+ The method is assigned to the OnClick event handler for the Find button in the CreateForm method. +

+ + + + + + + + + TButton.OnClick + - + Object (TFindDialog) for the event notification. - HelpClick - method to execute when the Help button is clicked. + Implements the OnClick event handler for the Help button on the dialog. - - + +

+ HelpClick is a method which implements the event handler signalled when the Help button on the dialog form is clicked. +

+

+ HelpClick calls the Help method to signal the OnHelpClicked event handler (when assigned). +

+

+ The method is assigned to the OnClick event handler for the Help button in the CreateForm method. +

+ + + + + + TButton.OnClick + - + Object (TFindDialog) for the event notification. - CancelClick - method to execute when the Cancel button is clicked. + Implements the OnClick event handler for the Cancel button on the dialog. - - + +

+ CancelClick is a method which implements the event handler signalled when the Cancel button on the dialog form is clicked. +

+

+ CancelClick calls the CloseDialog method to close the internal form instance for the dialog (when assigned). +

+

+ The method is assigned to the OnClick event handler for the Cancel button in the CreateForm method. +

+ + + + + + + + TButton.OnClick + - + Object (TFindDialog) for the event notification. - - - + + Get the value for the Height property. + + +

+ GetHeight is an overridden method in TFindDialog. It checks whether the internal TForm instance has been assigned for the dialog, and returns the form height when it is available. Otherwise, the inherited method is called to get the value in the Height member. +

+ + + + TControl.Height + - + + Value for the Height property. + - - - + + Gets the value for the Width property. + + +

+ GetWidth is an overridden method in TFindDialog. It checks whether the internal TForm instance has been assigned for the dialog, and returns the form width when it is available. Otherwise, the inherited method is called to get the value in the Width member. +

+ + + + TControl.Width + - + + Value for the Width property. + - DoCloseForm - execute the code for closing the Find/Replace dialog form. + Implements the OnClose event handler on the internal form displayed for the dialog. - - + +

+ DoCloseForm is a method which implements the event handler signalled when the internal form instance for the dialog is closed. No actions are performed in the method at design-time (csDesigning is in ComponentState property). +

+

+ DoCloseForm stores the Left and Top coordinates from the form to the corresponding properties in the class instance. The property values are assigned as default values when a new form instance is created in CreateForm. +

+

+ DoCloseForm is assigned to the OnClose event handler for the internal TForm instance when the Execute method is called. +

+ + + + + + + + TCustomForm.Close + TCustomForm.CloseQuery + TForm.OnClose + - + Object (TFindDialog) for the event notification. - + + Not used in the current implementation. + + + + + + Implements the OnShow event handler on the internal form displayed for the dialog. + + +

+ DoShowForm is a method which implements the event handler signalled when the internal form instance for the dialog is displayed. No actions are performed in the method at design-time (csDesigning is in ComponentState property). +

+

+ DoShowForm signals the OnShow event handler (when assigned) in TFindDialog to notify the dialog when the form calls its Show method. +

+

+ DoShowForm is assigned to the OnShow event handler for the internal TForm instance when the Execute method is called. +

+ + + + + TForm.OnShow + TCustomForm.Show + + + + Object (TFindDialog) for the event notification. - Find - software emulation of the OnFind event. + Signals the OnFind event handler when the Find button is clicked on the dialog form. - - + +

+ Find is called from the FindClick method, and occurs when the dialog is executed. An application must assign a TNotifyEvent routine to OnFind to perform the actions needed for the dialog. No actions are performed in the method if an event handler routine has not been assigned to OnFind. +

+ + + + + + TNotifyEvent + - Help - software emulation of the OnHelpClicked event. + Signals the OnHelpClicked event handler when the Help button on the dialog form is clicked. - - + +

+ Help is a method used to perform actions needed when the Help button on the dialog form is clicked. Help signals the OnHelpClicked event handler (when assigned) to perform the required actions. An application must assign a TNotifyEvent handler routine to OnHelpClicked. No actions are performed in the method when OnHelpClicked has not been assigned. +

+

+ Help is called from the HelpClick method, and occurs when the dialog is Executed. +

+ + + + + + TNotifyEvent + - Replace - software emulation of the OnReplace event. + Signals the OnReplace event handler when the Replace button is clicked on the dialog form. - - + +

+ Replace is introduced in TFindDialog, but it is used in the implementation of the TReplaceDialog descendant. +

+ + + + + + + + + + - CreateForm - function result returns the form that was created. + Creates and configures the internal form displayed for the dialog. - + +

+ CreateForm is a TForm function used to create the form displayed for the dialog. The form class is defined in the implementation section. It contains the controls needed for the edits, labels, buttons, radio buttons, and check boxes displayed for the dialog. It includes the controls needed to represent the TFindOption values in the Options property. +

+

+ CreateForm ensures that translated/localized resource strings are assigned to the captions for the form controls. OnClick event handlers are assigned for the Find, Help, and Cancel buttons on the form. The initial Left and Top coordinate are also assigned to the form. +

+

+ Use the OnFind, OnHelpClicked, OnShow, and OnClose event handlers to implement the specific actions performed when the dialog is executed. +

+

+ CreateForm is called from the Execute method when the form instance has not already been assigned. +

+ - + TForm instance created and configured for the dialog. - SetFormValues - specifies the values for the form. + Stores property values in the class instance to the controls on the dialog form. - - + +

+ SetFormValues copies values from the properties in the class instance to the controls displayed on the dialog form. This includes the values in FindText and Options. +

+

+ Enumeration values in Options are examined and applied to the radio button or check box used to represent a specific value. The Help button on the dialog form is made visible when frShowHelp is included in Options. The Scope check box is made visible when frHideEntireScope is not present in Options. +

+

+ SetFormValues ensures that the edit control for FindText is the active control on the form and its text content is selected. +

+

+ SetFormValues is called from the Execute method, and occurs after the form instance has been created and positioned. It is called before the form is displayed and executed using its buttons. +

+

+ See GetFormValues for the actions performed when the Find button is clicked on the dialog form. +

+ + + + + + + + - GetFormValues - finds the values for the form. + Retrieves values from the dialog form and stores them in the properties for the class instance. - - + +

+ GetFormValue is used to update the dialog class instance with the values entered on the dialog form at run-time. +

+

+ GetFormValue is called from the FindClick method which is used as the OnClick event handler for the Find button on the dialog form. It is called before the values in Options are sanitized and the Find method is called to perform the search. +

+

+ See SetFormValues for the actions performed to load properties to the dialog form. +

+ + + + + + + + + + - - - + + Determines the position for the dialog form and captures its coordinates. + + +

+ CalcPosition ensures that both the form and the class instance are updated with the location where the form is displayed. The Position property in the form instance is updated to display the form in the correct relative location. +

+

+ At design-time, the dialog form is aligned to the center of the Screen (poScreenCenter). +

+

+ At run-time, the dialog form is aligned to the center of the main form in the application (poMainFormCenter) when the Left and Top coordinates in the dialog are set to their unassigned values. The Left and Top coordinates are stored in the class instance for subsequent use in the CreateForm method. +

+ + + + + + TForm.Position + TControl.Left + TControl.Top + - + + TForm instance examined in the method. + - ReplaceText - the text string that is to be substituted for the Find text. + String with the value used to replace the value in FindText. - - + +

+ ReplaceText is introduced in TFindDialog, but it is used in the implementation of the TReplaceDialog descendant. +

+ + + + + + + - OnReplace - event handler for replacing text. + Event handler signalled to replace occurrence(s) of FindText with the value in ReplaceText. - - + +

+ An application must implement and assign a TNotifyEvent handler routine to OnReplace which responds to the event notification. +

+

+ The Sender argument contains the object instance with the TFindDialog or descendant for the event notification. It can be cast to a TFindDialog or a TReplaceDialog type to access properties and methods in the dialog class, including: FindText, ReplaceText, and Options. +

+

+ OnReplace is introduced in TFindDialog, but it is used in the implementation of the TReplaceDialog descendant. Use TReplaceDialog when the additional controls and buttons implemented in the replace dialog are needed. +

+ + + + + + + + + Constructor for the class instance.

- Create is the constructor for TFindDialog, and calls the inherited Create method. It sets the initial option values for Find only. + Create is the constructor for TFindDialog, and calls the inherited Create method. It sets the initial value in Options to [frDown]. It also stores the unassigned value (-1) for both the Left and Top properties in the class instance.

- TComponent.Create - TCommonDialog.Create + + + + + + @@ -2501,73 +2732,302 @@ ADialog.CustomColors.Values['ColorA'] := 'FFFF00'; Destructor for the class instance. - + +

+ Destroy is the overridden destructor for the class instance. It ensures that the internal TForm instance for the dialog form is freed (when assigned). Destroy calls the inherited destructor to perform and remove free notifications for the referenced counted component. +

+ - CloseDialog and returns its resources. + Closes the dialog form when its Cancel button is clicked. - - + +

+ CloseDialog is called from the CancelClick method (the OnClick handler for the Cancel button on the dialog form). CloseDialog ensures that the internal TForm instance for the dialog class has been assigned, and calls its Close method. This initiates a series of method calls and event handler notifications needed to close the form. +

+
+TCustomForm.Close ->
+  TCustomForm.OnClose ->
+    TFindDialog.DoCloseForm ->
+      TCommonDialog.OnClose
+
+ + + + + + + + + TCustomForm.Close + TCustomForm.OnClose + - - - + + + Displays the dialog form and responds to button clicks. + + +

+ Execute is an overridden Boolean function used to display the internal dialog form and respond to button clicks on the form. Execute reimplements the method defined in the ancestor class, and does not call the inherited method. +

+

+ If a TForm instance already exists in the dialog class, it is reused. If not, CreateForm is called to create and configure the TForm instance displayed for the dialog. The return value is False if a TForm instance was not successfully created in CreateForm. +

+

+ When a valid form exists for the dialog, it is positioned on the screen by calling CalcPosition. SetFormValues is called to transfer property values in the class instance to the dialog form. The Title, HelpContext, OnClose and OnShow properties in the form are updated and its Show method is called to display and execute the form. Values from the Height and Width properties in the form are stored in the dialog class for use as the default size. +

+

+ The return value is True if the form was successfully configured and displayed in the method. +

+

+ Use the OnFind, OnHelpClicked event handlers to perform actions needed when either the Find or the Help button on the dialog form is clicked. The Cancel button calls CloseDialog when the button is clicked. +

+ + + + + + + + + + + + + + + TCommonDialog.Execute - True if the dialog was successfully completed. + + True if the dialog was successfully configured and displayed in the method. + - The Left side of the dialog display. - - + Coordinate for the Left side of the dialog form. + +

+ Left is an Integer property which contains the horizontal coordinate where the left edge of the dialog form is located. The default value for the property is -1 and represents the unassigned value. +

+

+ The property value is read from the Left property in the internal TForm instance for the dialog (when assigned). Changing the value in the property causes the Left property in the dialog form to be updated with the new coordinate value. The value for the property is updated in the CalcPosition method when the dialog is executed. +

+

+ Left and Top are used in the CreateForm method to set the default coordinates for the dialog form. +

+ + + + + + + - The Position of the dialog display. - - + The position for the dialog form. + +

+ Position is a TPoint property with the coordinates where the dialog is displayed. The X and Y members in the TPoint instance contain the values from the Left and Top properties (respectively). Changing the value for the property causes the Left and Top properties to be updated with the new member values. +

+ + + + + TPoint + - the Top of the dialog display. - - + Coordinate for the Top edge of the dialog form. + +

+ Top is an Integer property which contains the vertical coordinate where the top edge of the dialog form is located. The default value for the property is -1 and represents the unassigned value. +

+

+ The property value is read from the Top property in the internal TForm instance for the dialog (when assigned). Changing the value in the property causes the Top property in the dialog form to be updated with the new coordinate value. The value for the property is updated in the CalcPosition method when the dialog is executed. +

+

+ Left and Top are used in the CreateForm method to set the default coordinates for the dialog form. +

+ + + + + + + - FindText - the text string that the dialog will try to find. - - + + Contains the text to locate when the Find button is clicked on the dialog form. + + +

+ FindText is a String property with the value to locate when Find button is clicked on the dialog form. Changing the value for the property causes the corresponding edit control on the dialog form to be updated (when assigned) with the new value. +

+

+ Use the OnFind event handler to perform the actions needed to located the value in FindText using the Options enabled for the dialog. +

+ + + + + - The current Options for the seeking and replacing process. - - + + Contains the find / replace options enabled for the dialog. + + +

+ Options is a TFindOptions property which contains the set of find / replace options enabled for the dialog. The set type contains zero (0) or more values from the TFindOption enumeration. The default value for the property is [frDown] and indicates the search direction in the dialog. +

+

+ Changing the values in the property causes the controls on the dialog form to be updated (when assigned). For example: +

+
+
frEntireScope
+
Causes the EntireScope check box to become checked.
+
frWholeWord
+
Causes the WholeWordsOnly check box to become checked.
+
frMatchCase
+
Causes the CaseSensitive check box to become checked.
+
+

+ Other values in Options control whether controls on the dialog form are visible or enabled, and are applied when the SetFormValues method is called. These include: +

+
+
frDown
+
Causes the DirectionRadioGroup box to be set to the Down radio button.
+
frDisableWholeWord
+
+ Causes the WholeWordsOnly check box to be disabled (Enabled = False) when present. +
+
frDisableMatchCase
+
+ Causes the CaseSensitive check box to be disabled (Enabled = False) when present. +
+
frDisableUpDown
+
+ Causes the Direction radio group be disabled (Enabled = False) when present. +
+
frHideWholeWord
+
+ Causes the WholeWordsOnly check box be hidden (Visible = False) when present. +
+
frHideMatchCase
+
+ Causes the CaseSensitive check box be hidden (Visible = False) when present. +
+
frHideUpDown
+
+ Causes the Direction radio group to be hidden (Visible = False) when present. +
+
frShowHelp
+
+ Causes the Help button to be displayed (Visible = True) when present. +
+
frHideEntireScope
+
+ Causes the EntireScope check box to be hidden (Visible = False) when present. +
+
+

+ Values in Options are updated in the GetFormValues method, which is called when the Find button is clicked on the dialog form. The Option values affected include: +

+
+
frDown
+
+ Added or removed based the radio button select in the Direction radio group. +
+
frWholeWord
+
+ Added or removed based on the checked state for the WholeWordsOnly check box. +
+
frMatchCase
+
+ Added or removed based on the checked state for the CaseSensitive check box. +
+
frEntireScope
+
+ Added or removed based on the checked state for the EntireScope check box. +
+
+ + + + + + + + + - OnFind - event handler for a click on the Find button. - - + + Event handler signalled when the Find button is clicked on the dialog form. + + +

+ OnFind is a TNotifyEvent property with the event handler signalled to perform the find operation for the dialog. OnFind is signalled (when assigned) from the Find method, and occurs when the Find button is clicked on the dialog form. +

+

+ An application must implement and assign a handler routine to the property to respond to the event notification. +

+

+ The Sender argument is the object instance for the event notification. It can be cast to TFindDialog (or TReplaceDialog in the descendent class) to access the properties and methods in the dialog class instance. Use its FindText and Options properties to perform the actions needed in the handler routine. +

+ + + + + + + + - OnHelpClicked - event handler for a click on the Help button. - - + + Event handler signalled when the Help button is clicked on the dialog form. + + +

+ OnHelpClicked is a TNotifyEvent property with the event handler signalled to display context help for the find dialog. It can be used to locate, format, and display the help associated with the dialog. OnHelpClicked is signalled from the Help method (when assigned), and occurs when the Help button is clicked on the dialog form. +

+

+ An application can implement and assign a handler routine to the property to respond to the event notification. The Sender argument contains the object instance for the event notification. It can be cast to TFindDialog (or TReplaceDialog for the descendent class) to access properties and methods specific to the dialog class instance. The handler routine is responsible for all aspects of the context help display. +

+

+ Include frShowHelp in the Options property to enable the Help button on the dialog form. +

+ + + + + + + + - A dialog allowing the user to replace text. + + Implements a find and replace dialog. +

The dialog appears and offers boxes for the user to enter text for searching and text to replace it, for example while editing a file or large piece of text. @@ -4688,6 +5148,81 @@ var A prompt to ask for the users input. + + + Displays a file open or save dialog to select a file name for the operation. + + +

+ PromptForFileName is a Boolean function used to display an Open or Save dialog using the values passed as arguments to the routine. It creates a TOpenDialog or a TSaveDialog instance for use in the routine. The AIsSaveDialog argument determines which dialog class is used in the routine. +

+

+ Argument values are assigned to the corresponding properties in the dialog class. The Execute method in the dialog class is called to perform file selection or creation as needed, and its return value is used as the return value for the routine. The return value is True when the Execute method for the dialog class returns True. +

+

+ AFilename contains the initially selected file name in the dialog, and is updated with the value selected using the dialog. A default value is not provided for the argument. If the dialog returns True, the FileName property in the dialog class is assigned to the AFileName argument. +

+

+ AFilter contains file masks that can be selected in the dialog. The default value is an empty string ('') and causes the all files mask ('*.*' or '*') to be used. See TFileDialog.Filter for more information about the notation allowed in the argument. +

+

+ ADefaultExt contains the file extension used for the file name selected in the routine. The default value for the argument is an empty string ('') and indicates that a default file extension is not used. See TFileDialog.DefaultExt for more information about default extensions. +

+

+ ATitle contains the caption displayed on the dialog. The default value is an empty string ('') and allows the default value provided by the dialog class to be used. +

+

+ AInitialDir indicates the initial directory when the dialog is displayed. The default value is an empty string ('') and causes the current directory in the application to be used as the initial directory in the dialog. +

+ + + + + + + + + + + + + + + + True if a file name was selected using the dialog. + + + + + Updated to contain the file name selected in open or save dialog. + + + + + File masks used in the dialog. + + + + + Default file extension for the file name selected in the dialog. + + + + + Title displayed on the dialog. + + + + + Initial directory displayed in the dialog. + + + + + True to create a save dialog, False to create an open dialog. + + + Base class for a dialog form used during copy to clipboard operations.