Contains common dialogs used in Lazarus LCL applications.

dialogs.pp contains classes, types, and routines used to implement common dialogs in an application. dialogs.pp is part of the Lazarus Component Library (LCL).

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

Dialogs Tab

TOpenDialog
TSaveDialog
TSelectDirectoryDialog
TColorDialog
TFontDialog
TFindDialog
TReplaceDialog
TTaskDialog

Misc Tab

TColorButton

Identifies a dialog type or style.

TMsgDlgType is an alias to the TMsgDlgType type in uitypes.pas.

UITypes.TMsgDlgType Identifies dialog button types.

TMsgDlgBtn is an alias to the TMsgDlgBtn type in uitypes.pas.

UITypes.TMsgDlgBtn Set with button messages for dialogs.

TMsgDlgButtons is an alias to the TMsgDlgButtons type in uitypes.pas.

UITypes.TMsgDlgButtons Alias to the TMsgDlgType enumeration value in uitypes. Alias to the TMsgDlgType enumeration value in uitypes. Alias to the TMsgDlgType enumeration value in uitypes. Alias to the TMsgDlgType enumeration value in uitypes. Alias to the TMsgDlgType enumeration value in uitypes. Alias to the TMsgDlgBtn enumeration value in uitypes. Alias to the TMsgDlgBtn enumeration value in uitypes. Alias to the TMsgDlgBtn enumeration value in uitypes. Alias to the TMsgDlgBtn enumeration value in uitypes. Alias to the TMsgDlgBtn enumeration value in uitypes. Alias to the TMsgDlgBtn enumeration value in uitypes. Alias to the TMsgDlgBtn enumeration value in uitypes. Alias to the TMsgDlgBtn enumeration value in uitypes. Alias to the TMsgDlgBtn enumeration value in uitypes. Alias to the TMsgDlgBtn enumeration value in uitypes. Alias to the TMsgDlgBtn enumeration value in uitypes. Alias to the TMsgDlgBtn enumeration value in uitypes. A set constant with Yes, No, Cancel buttons. A set constant used to show Yes, No, and Cancel buttons on a message dialog. A set constant with Yes, No buttons. A set constant used to show Yes and No buttons on a message dialog. A set constant to show an OK and a Cancel button on a message dialog. A set constant to show an OK and a Cancel button on a message dialog. A set constant to show an Abort, Retry , Ignore buttons on a message dialog. A set constant to show an Abort, Retry and Ignore buttons on a message dialog. A constant array used to convert the kind of message buttons to the kind of BitButton.

This array gives you for each possible button type in a messagebox the corresponding kind of BitButton.

For instance MsgDlgBtnToBitBtnKind[mbYes] has the value of bkYes.

It is the reverse of BitBtnKindToMsgDlgBtn.

A constant array used to convert the kind of BitButton to the kind of message buttons.

This array gives you for each BitButton the corresponding type of button on a message dialog. For instance BitBtnKindToMsgDlgBtn[bkOK] has the value of mbOK. It is the reverse if MsgDlgBtnToBitBtnKind.

Represents events handled in a custom-drawn widgetset.

Not used in the current LCL version.

Not used in the current LCL version. Not used in the current LCL version. Not used in the current LCL version. Not used in the current LCL version. Set type used to store values from the TCDWSEventCapability enumeration.

Not used in the current LCL version.

Specifies an event signalled when a result is returned in a dialog.

TDialogResultEvent is the type used to implement the OnDialogResult event handler in TCommonDialog.

Object for the event notification. True if the dialog was successfully executed. The base type from which other dialogs are derived.

TCommonDialog is the base type from which all other dialogs are derived.

Use Create to make an instance of the dialog, and the Execute method to show it to the user. Use the Close method to release it and free the used resources.

Sets the value for the Handle property. New value for the property. Implements the storage specifier for the the Title property.

Returns True when Title contains a value other than DefaultTitle.

True when an explicit value has been assigned to Title. The function that actually takes care of executing the dialog. Returns True if the correct exit button was pressed. DefaultTitle returns the default title for a dialog.

DefaultTitle returns an empty string ('') in TCommonDialog. The method is overridden in descendent classes to return the value needed for the derived class.

String used as the default title or caption for the dialog form. Gets the value for the Height property. Value for the property. Gets the value for the Width property. Value for the property. Sets the value for the Height property. New value for the property. Sets the value for the Width property. New value for the property. Resets the values in internal state flags for the dialog.

Called from the Execute method before the widgetset handle is allocated and the dialog is displayed.

Form which created the dialog class instance.

AttachTo is a platform-specific property which provides the form instance which created the dialog. It is used primarily for the MacOS Cocoa interface to provide the window handle needed for the platform.

Event handler signalled when a result is available for the dialog.

OnDialogResult is a TDialogResultEvent property with the event handler signalled when a result is available for the dialog.

OnDialogResult is a platform-specific property, and may not be used in all widgetsets. It provides a way for platforms which use native dialogs in their implementation to notify the dialog that a result is available.

Internal member used to store component style flags. Constructor for the class instance.

Create is the constructor for TCommonDialog, and calls the inherited Create method and adds default Title.

TComponent.Create The owner of the dialog: the component that called it. Displays the dialog and captures the result.

Use the Execute method to display the dialog and capture the result.

Execute notifies the Application that a modal display is started, and disables the current form. The widgetset handle is allocated for the dialog, and the DoExecute method is called to process the modal dialog. The form is re-enabled and its active control is re-selected. The Application is notified that the modal display is completed.

The return value is set to True if the OK button was pressed to exit the dialog.

Application TApplication.ModalStarted TApplication.ModalFinished Returns True if the user pressed the OK button. Operating system Handle for the dialog. UserChoice - the value selected by the user.

UserChoice is an name property which contains the modal result value returned for the dialog. It uses modal result constants like mrOk, mrCancel, et. al. as defined in the UITypes unit. Its value is updated by methods in the widgetset class when they display and process the dialog for the platform.

TModalResult Closes the dialog and frees its resources.

Close is a method used to perform actions needed to close the dialog. This can include signalling the OnClose event handler (when assigned and used for the platform). Close frees the widgetset Handle allocated for the dialog.

No actions are performed in the method if a Handle is not allocated for the dialog, or the Close method has already been called.

Close is called from the Execute method when the DoExecute method has been completed, and occurs before the active form is re-enabled and focused.

Performs actions needed when the dialog is displayed.

DoShow is a method used to perform actions needed when the form for the modal dialog is displayed. DoShow sets an internal flag to indicate that the dialog has been displayed, and signals the OnShow event handler (when assigned).

No actions are performed in the method if the dialog has already been displayed.

DoShow is called from the DoExecute method.

Performs actions needed to determine if the dialog can be closed.

DoCanClose is a method which determines if the dialog can be closed. It updates an internal flag which indicates the method has been called, and signals the OnCanClose event handler (when assigned and supported for the platform).

Use the OnCanClose to implement any required logic to determine if the dialog can actually be closed. The value in the CanClose argument is updated in the event handler.

DoCanClose is called from the DoExecute method when the widgetset class has attempted to close the dialog.

True if the OnCanClose event handler determines the dialog can be closed. Performs actions needed when the dialog is closed.

DoClose is a method used to perform actions needed when the dialog is closed. It updates an internal flag which indicates the method has been called, and signals the OnClose event handler (when assigned).

DoClose is called from the Close method, and occurs before the widgetset Handle for the dialog is freed.

Returns True if a widgetset handle has been allocated for the dialog. True if a widgetset handle has been allocated for the dialog. The width of the dialog. The height of the dialog. Event handler signalled when the dialog is closed. Event handler signalled to determine if the dialog can be closed. Event handler signalled when the dialog is displayed. Help context identifier for the help message displayed for the dialog. TApplication.HelpContext TCustomForm.HelpFile The Title or Caption displayed for the dialog.

Title can be used to provide a usage context for the re-usable dialog. It is defined using the TTranslateString type which allows the value to be recognized and translated using the localization facilities found in the LCL and the Lazarus IDE. When an explicit value has been assigned for the property, it is included the LCL component streaming mechanism.

The default value for the property is provided by the DefaultTitle method, and assigned in the Create constructor.

TTranslateString TFileDialog allows selection of a file from the current directory.

TFileDialog allows selection of a file from the current directory. This is also the base class for the Open and Save (As) dialogs.

Gets the value for the FilterIndex property. Value for the FilterIndex property. Set the value for the FileName property. New value for the FileName property. Sets the value for the Filter property. New value for the Filter property. Sets the value for the HistoryList property. New value for the HistoryList property. Constructor for the class instance.

Create is the constructor for TFileDialog, and calls the inherited Create method. It allocates resources needed for the files and history, and initializes the filter index.

TCommonDialog.Create Owner of the class instance. Destructor for the class instance.

Destroy is the destructor for TFileDialog, and frees file and history lists then calls the inherited Destroy method.

Performs actions needed to determine if the dialog can be closed.

DoCanClose is an overridden method in TFileDialog used to perform actions needed when an attempt is made to close the dialog. It ensures that the inherited method is called only when the OK button was pressed on the dialog. If the Esc key was pressed, or the dialog is closed using the close icon, the inherited method is not called. This prevents the OnCanClose event from being signalled when the dialog has actually been cancelled. CanClose is set to True in this situation.

This is done to maintain compatibility with Delphi VCL behavior.

Use the OnCanClose event handler to perform validation or error checking needed for the value in FileName. Set the value in its CanClose argument to False to prevent closing the dialog form.

Contains True if the dialog can be closed. False to prevent the dialog from being closed. Performs actions needed when the value in FilterIndex has been changed.

DoTypeChange is called when a new value is assigned to the FilterIndex property. It occurs after then value is FilterIndex has been stored to its property member.

DoTypeChange signals the OnTypeChange event handler (when assigned) using the TFileDialog instance as the control for the notification.

Stores the names of files (or directories) selected using the dialog.

Files is a TStrings property used to store values selected using the file dialog. A TStringList instance is created and assigned to the property in the Create constructor.

Files is used in descendent classes, like TOpenDialog and TSelectDirectoryDialog, to store the directory or one or more file names chosen using the derived classes.

Use HistoryList to access the list of previous file or directory names used in the derived dialog classes.

TStrings TStringList HistoryList - stringlist containing the names of files recently accessed.

HistoryList is a TStrings property used to store the previous values selected using the file dialog. A TStringList instance is created and stored to the property in the Create constructor.

HistoryList is used in descendent classes, like TOpenDialog and TSelectDirectoryDialog, to store values that have previously been assigned to the FileName property.

Use FileName or Files to access the directory or one or more file names selected using the derived classes.

TStrings TStringList Signals the OnTypeChange event handler when the value in FilterIndex is changed by the widgetset class instance.

IntfFileTypeChanged is a callback routine used by the widgetset class when it applies a change to the value in the FilterIndex property. It occurs when the FilterIndex returned from the native dialog is handled by the widget.

IntfFileTypeChanged stores the value in NewFilterIndex to its internal member, and calls DoTypeChange to signal the OnTypeChange event handler (when assigned).

Use the OnTypeChange event handler to perform actions needed when the value in FilterIndex has been modified.

New value for the FilterIndex property. Contains the default extension for file names in the dialog.

DefaultExt is a String property which contains the default file extension used for the FileName or Files in the file dialog. It can contain a value like 'pas' or '.pas'. If the Period character is not present in the first position, it is inserted before the property value is stored.

DefaultExt is used in descendent classes, like TOpenDialog, and provides the value that is appended to a file name when an extension or a Filter has not been provided.

Contains the UTF-8-encoded name for a file chosen using the dialog.

FileName is a String property with the name for a file chosen using the dialog. As a String type, it can contain UTF-8-encoded values. If you need the file name using the system encoding, you can use UTF8ToSys from the LazUTF8 unit.

The value in FileName may be used in a different context in descendent classes. For example, it represents a directory name in the TSelectDirectoryDialog descendant.

UTF8ToSys A string which contains possible filename filters (e.g. .doc, .xmp, .pas etc).

This is a string which contains the filters a user can choose from. The available filters and their description are separated by pipe symbols.

To set this property at run-time assign a value like:

'All files|*.*|Lazarus Project files|*.lpr'

An entry can contain multiple masks separated by semicolon, like:

'Pascal units|*.pas;*.pp;*.p|All files|*.*' This property sets which file filter is the default.

This property sets which file filter is the default. For example, set this property to 2 to set the second filter as default.

Contains the initial directory displayed when the dialog is opened.

InitialDir is a String property which contains the name for the initial directory displayed when the dialog is opened. When omitted, or set to an empty string, the directory for the application executable is used.

Assign the value in InitialDir prior to calling the Execute method to display the dialog.

For the windows platform, there are some CLSID values which can be used in InitialDir. They are GUIDs representing locations like 'This PC' or 'Network' used the Windows file explorer. The following values are know to work in InitialDir:

Opens 'This PC': '::{20D04FE0-3AEA-1069-A2D8-08002B30309D}'
Opens Network: '::{F02C1A0D-BE21-4350-88B0-7367FC96EF3C}'

There are others which may, or may not, work for your Windows version:

List of Windows 11 CLSID Key (GUID) Shortcuts

Event handler signalled when the Help button is clicked.

Used at run-time when a widgetset class responds to a Help button click. The Sender argument is the dialog instance for the event notification.

TNotifyEvent Event handler signalled when the selected file type or filter index is changed.

Used at run-time when the FilterIndex value is changed in a widgetset class. The Sender argument is the dialog instance for the event notification.

TNotifyEvent Options which can be used in a TOpenDialog instance.

TOpenOption contains a list of possible options which can be used in an Open dialog. Values from the enumeration are stored in the TOpenOptions set type which is used to implement the Options property in TOpenDialog. When an option value is included in the set, it is enabled during execution of the dialog. The values are applied to the native dialog before it is executed.

Please note that some option values may not be available for a given platform where the LCL is supported: ofNoDereferenceLinks, ofOldStyleDialog, ofViewDetail, and ofAutoPreview.

Include read-only files. If selected file exists shows a message, that file will be overwritten. Hide read only files. Do not change the current directory. Show a help button. Disables file name validation using OFN_NOVALIDATE on the Windows platform. Allows file names with invalid characters. Enables multi-selection in a dialog. Allows a file name with an extension which does not match the filters or default extension in a file dialog. Shows an error message if selected path does not exist. Shows an error message if selected file does not exist. Enables a verification prompt when a file or directory needs to be created for a file dialog. Includes the OFN_SHAREAWARE flag on the Windows platform. Do not return file names that are read-only. Includes the OFN_NOTESTFILECREATE flag on the Windows platform. Disables and hides the Network button on the Windows platform. Disables long file names on the Windows platform. Used in classic-style dialogs to force use of file names using the 8.3 format. Explorer-style dialogs ignore this flag and always display long file names. Prevents use of the OFN_EXPLORER and dependent flags in dialogs on the Windows platform. Do not resolve links while dialog is shown (only on Windows, see OFN_NODEREFERENCELINKS). Do not resolve links after Execute. Not used in the current LCL version. Dialog can be resized, e.g. via the mouse. Do not add the path to the history list. Show hidden files. Details are OS and interface dependent. OS and interface dependent. Set type used to store TOpenOption enumeration values.

TOpenOptions is a set type used to store 0 (zero) or more values from the TOpenOption enumeration. TOpenOptions is the type used to implement the Options property in TOpenDialog. When a value s included in the set, it is enabled during execution of the dialog.

Set constant with the default Open Dialog options used in TOpenDialog.

Contains the following values from the TOpenOption enumeration:

ofEnableSizing: Allows the dialog to be resized.
ofViewDetail: Enables the file detail view in the QT4 and QT5 widgetsets. Not implemented for any other platforms in the current LCL version.

DefaultOpenDialogOptions is used as the default value for the Options property in TOpenDialog.

Implements a File / Open dialog used to select one or more files on the local file system.

TOpenDialog is a TFileDialog descendent which implements a dialog used to select one or more files that can be opened in an application. TOpenDialog is implemented as a wrapper for the native file selection dialogs on the various platforms / widgetsets.

Use the Options property to configure the features and behaviors enabled when the dialog is executed. Please note that some of the options are platform-specific, and may not be available on all of the platforms supported by the Lazarus LCL.

Use InitialDir to specify the directory with the files displayed when the dialog is executed.

Use the event handlers to perform actions needed when the directory or file selection(s) is changed during execution of the dialog.

Use the FileName or Files properties to access the file(s) selected using the dialog.

Use the Filter and FilterIndex properties to determine the file extensions displayed in the dialog. Use the OnTypeChange event handler to perform actions needed when the active filter is changed.

Use the UserChoice property to determine the button pressed to close the dialog.

Gets physical file names for symbolic links or file references.

ResolveLinks is a procedure used to get physical file names for file references or symbolic links used in the Filename and Files properties.

Called from DereferenceLinks when the dialog is executed and ofNoResolveLinks is NOT included in the Options property.

Ensures the specified file name meets the requirements for the dialog.

CheckFile is a Boolean function used to examine and update the specified file name. AFilename is a variable argument which contains the path to the file and can include its extension. The return value is True if the file name satisfies the filter, extension, and options used for the open dialog.

Values in DefaultExt, Filter, and FilterIndex are used to get a file extension when AFilename does not already include one. The file extension is appended to the value in AFilename.

Values in Options are used to determine if the file name is usable, including:

ofPathMustExist: The path in AFilename must already exist on the local file system. If it does not exist, a rsfdPathNoExist message is displayed and the method is exited.
ofFileMustExist: Calls CheckFileMustExist to ensure that the file already exists on the local file system. A message is displayed if the file name and extension are not found, and the method is exited.
ofNoReadOnlyReturn: The file and / or directory in AFilename must be writable. A rsfdFileReadOnly is displayed if the file or directory is read-only, and the method is exited.

CheckFile is used in the CheckAllFiles method to validate the entries in the Files property.

Modified in LCL version 2.2.6 to include an additional helper function (ExtractFilterValues) in the implementation. True if the file name is valid for the open dialog. Fully-qualified file name or directory path examined and possibly updated in the method. Determines whether the specified file name exists.

CheckFileMustExist is a Boolean function used to check whether the file in AFilename exists on the local file system. The return value is True when FileExistsUTF8 finds the specified file name. If the file is not found, an error message is displayed with the value in rsfdFileNotExist.

CheckFileMustExist is used in the implementation of the CheckFile method.

True if the specified file exists on the local file system. File name (including path) checked in the method. Ensures that values in the FileName and Files properties are valid for the Options in the dialog.

CheckAllFiles is a Boolean function used to validate values in the FileName and Files properties using the Options enabled for the dialog.

FileName is checked when a non-empty string value has been assigned to the property, or when ofAllowMultiSelect has been omitted from the Options property. The lines of text in the Files property are validated when ofAllowMultiSelect has been included in the Options property.

CheckAllFiles calls the CheckFile method to validate and potentially update a file name. A file name modified in CheckFile to include a file extension is stored in the origin property (FileName or Files).

The return value is True if the file name(s) meet the requirements for the Options property and the local file system.

True if the file names are valid for Options in the dialog. Performs actions needed to display the dialog and capture its result.

DoExecute is an overridden Boolean function in TOpenDialog, and calls the inherited method on entry. It extends the execution loop for the dialog to use the Options enabled for the dialog, including:

ofNoResolveLinks: Calls ResolveLinks to follow symbolic links when ofNoResolveLinks has been omitted.
ofNoChangeDir: Updates the InitialDir property when a path in FileName or Files is changed and ofNoChangeDir has been omitted.

If execution of the inherited method was successfully completed, the CheckAllFiles method is called to validate the values in the FileName and Files properties.

The return value is True when all of these steps are successfully completed.

True when the selected file(s) are valid and the method is successfully completed. Gets the default title used for the Open Dialog.

DefaultTitle is overridden in TOpenDialog to return the default title for the dialog. Uses the value in rsfdOpenFile as the return value.

Used in the inherited constructor to set the default value for the Title property.

rsfdOpenFile Default title for the dialog. Constructor for the class instance.

Create is the constructor for TOpenDialog, and calls the inherited Create method then loads the default options for the dialog.

TFileDialog.Create Owner of the class instance. Performs actions to determine if the dialog can be closed.

DoCanClose is an overridden method in TOpenDialog. It ensures that a dialog using the classic style (where ofOldStyleDialog is included in Options) does not call the OnCanClose event handler in the inherited method. In this situation, the CanClose argument is set to True and the internal flag used in the execution loop is set indicating that DoCanClose was called.

This behavior is Delphi VCL compatible.

For Explorer-style dialogs (where ofOldStyleDialog is not included in Options), the inherited method is called. This allows the CanClose argument to be updated when the OnCanClose event handler is signalled.

Variable argument which indicates if the dialog can be closed. Signals the OnFolderChange event handler when a new directory is selected during execution of the dialog.

DoFolderChange is a method used to perform actions needed when a new directory is selected using the open dialog. DoFolderChange signals the OnFolderChange event handler (when assigned) using the dialog instance as the object for the notification.

DoFolderChange is called from the widgetset class when directory navigation has occurred in the native dialog. FileName contains the path for the newly selected directory when the method is called.

Use InitialDir to specify the initial directory displayed when the dialog is executed.

Use OnSelectionChange to perform actions needed when a new file is selected using the dialog and the value in FileName is modified.

Performs actions when the selected file in FileName has been changed.

DoSelectionChange is a method used to perform action needed when the selected file in the dialog has been change. It is called from methods in the widgetset class when a new value has been assigned to the FileName property.

DoSelectionChange updates an internal member used to track the current and previous value for the FileName property. It signals the OnSelectionChange event handler (when assigned) using the dialog class instance as the object for the notification.

Use HistoryList for the previously selected file name values in the dialog.

Implements the callback used to update values in Options when the widgetset class processes the dialog result. TOpenOption enumeration value updated in the Options for the dialog. True to include the option in the class instance. False to exclude the option. Options to be used for this dialog.

Options is a TOpenOptions property with the set used to store options enabled in the dialog. Options contain 0 (zero) or more values from the TOpenOption enumeration. When a value is included in the set, it is enabled when the dialog is executed.

The default value for the property is defined in the DefaultOpenDialogOptions constant, and contains:

ofEnableSizing: Allows the dialog to be resized at run-time.
ofViewDetail: Enables the file detail view in the QT4 and QT5 widgetsets. Not implemented for any other platforms in the current LCL version.

See for a complete list of enumeration values and their meanings.

Values in Options are used at run-time in methods like:

CheckAllFiles
CheckFile
DoExecute
DoCanClose

In addition, values in Options may be updated when the IntfSetOption callback method is used to apply changes from the widgetset class instance.

Event signalled when a new directory is selected in the dialog.

OnFolderChange is a TNotifyEvent property with the event handler signalled when the current directory is changed using the dialog. OnFolderChange is signalled (when assigned) from the DoFolderChange method when it is called from methods in the widgetset class instance. It is called when the value in FileName has been changed as a result of directory navigation using the native dialog for the platform.

The dialog class instance is used as the Sender object for the event notification.

Please note that changing the current folder (and updating FileName with the new directory) will also trigger the OnSelectionChange event.

Event triggered when the user changes the folder of file selection(s) made in the OpenDialog.

OnSelectionChange is a TNotifyEvent property with the event handler signalled when the folder or file selection for the dialog has been changed. It is signalled (when assigned) from the DoSelectionChange method. The dialog class instance is used as the object for the notification.

OnSelectionChange occurs at run-time when the value in FileName is changed using the native dialog for the platform. The value in FileName has been updated and also stored as the text value for the Files property prior to the event.

When multi-selection is enabled by including ofAllowMultiSelect in Options, OnSelectionChange is signalled for the first value in the range of selected files only. It will, however, be signalled again when the first selection is changed. Other selected file names in Files, which are not the first selected file, are not signalled at all.

Please note that both the OnSelectionChange and OnFolderChange events are signalled during execution when the folder (or directory) is changed to value that does not match the previous value in FileName. OnSelectionChange is signalled first.

TSaveDialog - Dialog for saving the current buffer to a file.

TSaveDialog is a TOpenDialog descendant which implements a dialog used when an application needs to save a file. It is a wrapper for the native Save / Save As dialogs on the platforms where the LCL is supported.

TSaveDialog extends the ancestor class to provide the correct default title for the derived dialog class.

TSaveDialog is used to implement the TFileSaveAs dialog defined in the stdactns.pas unit.

TFileSaveAs Gets the default title used for the Save Dialog.

DefaultTitle is overridden in TSaveDialog to return the default title for the dialog. Uses the value in rsfdFileSaveAs as the return value.

Used in the inherited constructor to set the default value for the Title property.

rsfdFileSaveAs Default title for the dialog. Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry. Create updates the component style flags to the value needed (csSaveFileDialog) for the dialog type.

csSaveFileDialog Owner of the class instance. Implements a select directory dialog.

TSelectDirectoryDialog is a TOpenDialog descendant which allows the user to select a directory name by navigating file system entries. It is implemented using the native selection dialog for the platform.

Use the InitialDir property to specify the active directory when the dialog is displayed.

The FileName property contains the selected directory when the dialog is closed using the 'Select Folder' button.

The Options property can be used to control the features and behaviors enabled for the selection dialog.

Use the OnFolderChange event handler to perform actions when a new directory is entered / chosen during navigation on the dialog.

Use the OnSelectionChange handler to perform actions when a new directory is selected or highlighted using the mouse or cursor keys on the dialog.

TDirectoryEdit Checks whether a specified directory already exists, and displays a message when missing.

CheckFileMustExist is an overridden Boolean function in TSelectDirectoryDialog. It is check whether the directory specified in AFilename already exists on the file system. The return value is True if the directory in AFilename already exists. It is False if the directory does not exist.

CheckFileMustExist re-implements the method inherited from TOpenDialog to use directory-specific resource strings when messages are displayed for a missing value in AFilename.

CheckFileMustExist is called from the CheckFile method in TOpenDialog.

DirPathExists True if the specified directory exists, and False when it is missing. Directory name examined in the method. Gets the default title for the dialog.

DefaultTitle is an overridden String function used to get the default title displayed on the directory selection dialog. It returns the value assigned to the rsfdSelectDirectory resource string used in the LCL.

rsfdSelectDirectory Constructor for the class instance.

Create is the overridden constructor for the class instance. It calls the inherited constructor on entry, and sets the component style flag to the value csSelectDirectoryDialog.

csSelectDirectoryDialog Owner of the class instance used in notification events. Implements a dialog used to select a TColor value.

TColorDialog is a TCommonDialog descendant which implements a dialog used to select a color value from a palette of colors. It is a wrapper for the native color selection dialog on platforms supported by the LCL (when available).

The dialog allows a TColor value to be selected from a group of predefined basic colors, custom colors, or using a color wheel or pad. On some platforms, the color can be specified using RGB or HSL (Hue, Saturation, Luminosity) values.

Use the CustomColors property to define color values using identifiers and hexadecimal RGB values for the custom colors.

Set the value for the Title property (when needed) prior to displaying the color selection dialog.

Call the Execute method to display the color dialog and capture the color value. If the user clicks on the OK button in the dialog, the selected color value is returned in the Color property and the UserChoice property is set to mrOK. A value other than mrOK indicates that the color selection dialog was cancelled or closed without selecting a color value.

Internal member used to store the value for he selected color. Internal member used to store user-specified colors. Sets the value for the CustomColors property. New value for the CustomColors property. Adds a value to the CustomColors property. String with the identifier and hexadecimal RGB color value added in the method. Gets the default title used in the caption for the color selection dialog.

The return values contains the string data found in the rsSelectcolorTitle constant.

TCommonDialog.DefaultTitle Returns the values defined in the rsSelectcolorTitle constant. Constructor for the class instance.

Create is the constructor for TColorDialog, and calls the inherited Create method. Create allocates resources and initializes the Color and CustomColors properties.

TCommonDialog.Create Owner of the class instance. Destructor for the class instance.

Destroy is the overridden destructor for TColorDialog. It frees resources allocated for the CustomColors property and calls the inherited Destroy method.

TLCLComponent.Destroy The Title or Caption displayed in the title bar for the dialog.

Title can be used to provide a usage context for the re-usable dialog. The default value for the property is provided by the DefaultTitle method. Set the value for the property before calling the Execute method.

For the macOS Carbon widgetset, the Title property is not supported. TCommonDialog.Title Color selected by the user in the color dialog.

Color is a TColor property with the color selected using the dialog. A value can be pre-set in Color and accepted, but a new value may also be chosen. When the Color dialog is displayed and the user pressed OK, the Color property contains the chosen color.

Use CustomColors to define a palette with color names and their hexadecimal values available in the dialog.

Defines the color names and values available in the color dialog.

CustomColors is a TStrings property which contains the color names and hexadecimal values available in the color dialog. It allows a custom color palette to be used in place of the default colors for the platform.

Values added to CustomColors are in the "name=hexvalue" format. For example:


ADialog.CustomColors.Add('ColorA=FFFF00');
// or
ADialog.CustomColors.Values['ColorA'] := 'FFFF00';

The hexadecimal color value is 6-digits representing the RGB components for the color.

The default values in CustomColors are assigned in the Create constructor to the standard and extended colors for the platform. It does not include the equivalents for clDefault and clNone.

Use Color to get the TColor value selected using the dialog when the Execute method was called.

TColorButton - a SpeedButton designed to be used with the Color dialog, allowing a color to be selected for text or graphics.

To use the ColorButton, first select the ColorButton icon from the Component Palette and place it on the Form Designer in the location you want it to occupy, then place a TColorDialog on the Form Designer, give it a name (or accept the default name) and select this named dialog as the ColorDialog property in the Object Inspector for the ColorButton.

The default appearance of the ColorButton is a rectangle containing a color; if you wish to include a caption beside the block of color, you may need to adjust the size of the control to accommodate the text, and you can then enter some text in the Caption property of the ColorButton; this text will appear next to the color block.

At run-time the ColorButton is visible with a default or preselected ButtonColor in the block, and any optional caption beside it; the ColorDialog is not visible until the ColorButton is clicked, when the ColorDialog pops up and offers a choice of colors, either from a list or a palette, and if the user makes a selection and closes the dialog by pressing OK, the ColorButton will display the color that was chosen in the ColorDialog.

Note that in the context of ColorButton, properties with the name ButtonColor refer to the color that has been selected and is displayed in the color block; properties entitled Color without 'Button' attached refer to the color of the control itself, usually the same as the background or the default button face color.

Implements the storage specifier for the ButtonColorAutoSize property. True when ButtonColorAutoSize is set to False. Sets the value for the BorderWidth property. New value for the BorderWidth property. Sets the value for the ButtonColor property. New value for the ButtonColor property. Sets the value for the ButtonColorAutoSize property. New value for the ButtonColorAutoSize property. Sets the value for the ButtonColorSize property. New value for the ButtonColorSize property. Applies auto-layout changes using the specified policy and scaling proportions to the control.

DoAutoAdjustLayout is an overridden method in TColorButton used to implement changes to control and border sizes for the AutoAdjustLayout method. These methods are called when High-DPI and scaling have been enabled in the project options for an application.

AMode indicates the automatic layout policy applied in the method. It is a value from the TLayoutAdjustmentPolicy enumeration, and determines whether horizontal / vertical / or both sizes are adjusted in the method. It generally reflects the constraints for the device type where the application is running.

AXProportion and AYProportion contain the scaling factors applied to the horizontal and/or vertical sizes.

DoAutoAdjustLayout calls the inherited method on entry. It extends the method to update the ButtonColorSize and BorderWidth properties when AMode indicates that either horizontal or high DPI scaling are used.

TControl.DoAutoAdjustLayout Added in LCL version 3.0. Identifies the auto-layout policy applied in the method. Scaling factor for horizontal dimensions. Scaling factor for vertical dimensions. Re-implements drawing the glyph for the control to use the selected color.

DrawGlyph is an overridden method in TColorButton. It re-implements the ancestor method to draw the button face and color block (or swatch) for the control using the arguments passed to the method.

The value in AState determines the appearance for the glyph (color swatch). When set to bsDisabled, a bitmap with a disabled pattern (dotted lines) is drawn using the Color for the button face. Otherwise, the value in ButtonColor is used to draw the glyph. GetGlyphSize is called to get the dimensions for the glyph based on the settings in ButtonColorAutoSize and ButtonColorSize.

The return value is a TRect instance with the bounds affected in the drawing operation.

DrawGlyph calls the Rectangle method for the TCanvas instance in the Canvas argument using the return value for the method as an argument.

DrawGlyph does not call the inherited method which draws the glyph image for the speed button.

DrawGlyph is called from the MeasureDraw method in the ancestor class.

TCustomSpeedButton.DrawGlyph TCustomSpeedButton.MeasureDraw TButtonState Rectangle where the color block is drawn for the control. Drawing surface where the control is drawn. Client rectangle where the button face / color block is rendered. TPoint with horizontal and vertical offsets in AClient where the glyph is drawn. Button state for the glyph; bsDisabled draws the disabled pattern for the button control. Not used in the method. Not used in the method. Gets a bitmap with the disabled pattern for the control.

GetDisabledPattern is a TBitmap function used to get the bitmap with the disabled pattern drawn on the control. It is used when the Enabled property (in the control or one of its parents) is set to False.

GetDisabledPattern ensures that a TBitmap instance has been created and assigned to an internal member for the class instance. The bitmap contains a pattern with dotted lines that indicate the control cannot accept input values. The allocated bitmap is freed (when assigned) in the destructor for the class instance.

GetDisabledPattern is called from the DrawGlyph method when its button state argument is set to bsDisabled.

TBitmap instance with the disabled pattern drawn for the control. Gets the size for the glyph (color block / swatch) on the button control.

GetGlyphSize is an overridden TSize function used to get the dimensions for the glyph (color block / swatch) displayed on the button control. Values in ButtonColorAutoSize and ButtonColorSize determine the height and width used for the color block displayed on the control.

When ButtonColorAutoSize is set to True, the color block is auto-sized to fill the unused client area for the control specified in the PaintRect argument. Space is reserved for the Caption (color name), Spacing, BorderWidth, and Margin properties assigned to the control.

When ButtonColorAutoSize is False, ButtonColorSize is used as both the width and height for the color block.

The return value is a TSize instance where the width and height for the color block are stored in the CX and CY members (respectively). Layout determines whether spacing is reserved in the horizontal (blGlyphLeft, blGlyphRight) or vertical (blGlyphTop, blGlyphBottom) dimensions.

TControl.Caption TSize instance with the dimensions for the glyph (color block). True if a drawing operation is active; never set to False in LCL code. TRect instance with the display area for the button control. Performs actions when the specified component is added to or removed from the control.

Notification is an overridden method in TColorButton, and calls the inherited method on entry. It ensures that the ColorDialog property is set to Nil when AComponent and Operation indicate the dialog class instance has been removed from the control.

Component for the notification. Operation performed for the specified component. Displays a Color dialog and captures its result.

ShowColorDialog is a method used to display a TColorDialog and capture its result.

ShowColorDialog uses an existing dialog instance in ColorDialog when assigned. Otherwise, a new TColorDialog instance is created and temporarily stored in the property. The value in ButtonColor is used as the default color value in the dialog. The Execute method in the dialog is called to get the selected TColor value, and it is stored in the ButtonColor property.

Constructor for the class instance.

Create is the constructor for TColorButton, and calls the inherited Create method. Create sets the initial bounds for the controls to their default values, and sets the values for properties including:

ButtonColorSize (16)
BorderWidth (2)
ButtonColorAutoSize (True)

TCustomSpeedButton.Create Owner of the class instance. Destructor for the class instance.

Destroy is the overridden destructor for the class instance. It ensures that the internal bitmap with the pattern displayed for the disabled control is freed (when assigned). Destroy calls the inherited destructor prior to exiting from the method.

TCustomSpeedButton.Destroy Performs actions needed when the control is clicked.

Click is an overridden method in TColorButton used to perform actions needed when the control is clicked or the Space key is pressed when the control has focus. It calls the inherited method on entry to execute the Action for the control, or signal its OnClick event handler (when assigned). It calls the ShowColorDialog method to configure, display, and execute the ColorDialog for the control. ButtonColor is updated to contain the new color selected when the dialog was executed.

TCustomSpeedButton.Click TControl.Click Width for the borders on the button control. True if the color block for the button can be automatically resized to fill the unused client area.

ButtonColorAutoSize is a Boolean property which indicates if the color block for the button can be automatically resized to fill the unused client area in the button control.

When set to True, the client area is examined to determine the dimensions for the color block. Space is reserved using the Caption, BorderWidth, Spacing, and Margin properties defined for the control. The unused area in the client rectangle is drawn using a frame filled with the selected ButtonColor for the control.

When set to False, the value in ButtonColorSize is used as both the height and width for the color block or swatch.

The default value for the property is True as assigned in the constructor for the class instance. Setting a new value for the property causes the control to be redrawn. When ButtonColorAutoSize is True, setting a new value for BorderWidth also causes the control to be redrawn.

ButtonColorAutoSize and ButtonColorSize are used in the GetGlyphSize method.

TControl.Caption Size of the color block (or swatch) on the button control.

ButtonColorSize is an Integer property with the size for the color block (or swatch) displayed on the control. The default value for the property is 16 (pixels) as assigned in the constructor for the class instance. Its value is used in the GetGlyphSize method when ButtonColorAutoSize is set to False, and represents both the width and height returned for the button glyph.

Changing the value for the property causes the control to be redrawn.

The TColor value selected in the button control.

ButtonColor is a TColor property which contains the selected color for the button control.

The value in ButtonColor is used as the initial selected color value when the ColorDialog is displayed in the ShowColorDialog method. It is updated with the newly selected color value when the ColorDialog is executed.

Setting a new value for the property causes the OnColorChanged event handler to be signalled (when assigned) and the control is redrawn.

Use Color to set the color used for the button face on the control.

TColor The color selection dialog displayed when the control is clicked, or the ShowColorDialog method is called.

ColorDialog is a TColorDialog property which contains the color selection dialog displayed for the button control. ColorDialog is used in the ShowColorDialog method. A TColorDialog instance is created if one has not already been assigned to the property. It is freed (when created) when the color selection dialog is closed. A TColorDialog instance not created by the button control is not freed prior to exiting from the method or destroying the control.

The value in ButtonColor is assigned as the initial color selection for the dialog, and the Execute method in the dialog is called to capture the newly selected color value (when available). The new color selection is stored in the ButtonColor property.

Text displayed next to the color block on the button control.

Caption is a String property with the text displayed beside the color block (or swatch) on the button control. When it has been assigned a non-empty value, space is reserved on the client area for the text plus the number of pixels in Spacing. When empty, no space is reserved for the text or the space between the text and the color block.

In general, Caption can be used to provide a human-readable value for the selected color in ButtonColor. The value in Caption is not, however, automatically linked to the selected color value. Use the OnColorChanged event handler to update the value in Caption as needed when the color selection has been changed.

The Layout property determines the order of the Caption and color block values on the button surface. Layout refers to the alignment for the glyph (color block).

Set ButtonColorAutoSize to True to allow the color block to fill the unused client area for the control. Use ButtonColorSize to set the dimensions for the color block when ButtonColorAutoSize is False.

The Color of the control itself, i.e. the parts that are not the color display block; edges, background etc. TCustomSpeedButton.Color Event handler signalled when the button color has been changed.

OnColorChanged is a TNotifyEvent property with the event handler signalled when the selected color in ButtonColor has been changed. An application must implement and assign an object procedure to the property to respond to the event notification.

OnColorChanged is signalled (when assigned) when a new TColor value is assigned to the ButtonColor property. A common use for the event handler is to update the value in Caption when the value in ButtonColor has been updated. OnColorchanged is not signalled during LCL component streaming (csLoading in ComponentState).

TNotifyEvent An enumerated list of constants to set the options of a Font dialog. Limits the font name selection list to font using ANSI character sets. Limits the font name selection list to TrueType fonts. Displays check boxes for strike-through, underline, et. al. font effects in the dialog. Limits the font name selection list to fixed-pitch (mono-spaced) fonts. 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. Excludes OEM fonts from the font selection list. Excludes bitmapped fonts that emulate sizes by scaling. Hides the Size selection list in the dialog. Hides the style selection list in the dialog. Excludes vector fonts from the list of font names. Makes the Help button visible in the dialog. Displays font names using a WYSIWYG preview. Restricts font sizes to the range in MinFontSize and MaxFontSize. Limits the font selection list to scalable fonts; no bitmapped fonts. Makes the Apply button visible in the dialog. Set type used to store font dialog options. Dialog used to select a font typeface and size.

TFontDialog is a TCommonDialog descendant which implements a font selection dialog.

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.

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. Please note that the Apply button is available on the GTK2, GTK3, and Windows platforms. It is not currently implemented for QT platforms.

Sets the value for the Font property. New value for the property. Performs actions needed when a font is selected using the dialog.

ApplyClicked is a used to perform actions needed when a font is applied using the Apply button in the dialog. The Apply button is made visible by a setting in Options, and must be enabled; the default buttons are Ok and Cancel.

ApplyClicked signals the OnApplyClicked event handler (when assigned).

Widgetset classes in the current LCL implementaion do not call ApplyClicked; they signal the OnApplyClicked event handler directly. Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry. Create allocates resources needed for the Font property, and sets the default values in the Options property.

Owner of the class instance. Destructor for the class instance. 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. 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.

TFont Minimum font size allowed in the font selection dialog.

MinFontSize is an Integer property which contains the minimum font size allowed in the font selection dialog. Limiting font size selection to the range in MinFontSize and MaxFontSize must be enabled by including fdLimitSize in the Options property.

Maximum font size allowed in the font selection dialog.

MaxFontSize is an Integer property which contains the maximum font size allowed in the font selection dialog. Limiting font size selection to the range in MinFontSize and MaxFontSize must be enabled by including fdLimitSize in the Options property.

A set of TFontDialogOption options enabled for the dialog.

Options is a TFontDialogOptions property which controls the options enabled for the font selection dialog. Options contains zero or more values from the TFontDialogOption enumeration. The default value for the property is [fdEffects], and enables the font effects check boxes in the dialog.

See TFontDialogOption for more information about the values in the enumeration and their usage.

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 a platform. Some options may not be available on a given platform. For example, the Apply button enabled using fdApplyButton is not implemented for all of the LCL platforms. It is not currently implemented in the QT widgetsets. Event handler signalled when the Apply button is clicked in the font dialogs.

OnApplyClicked is a TNotifyEvent property with the event handler signalled when the Apply button is clicked in the font dialog. The Apply button must be enabled in the Options property to receive the event notification.

OnApplyClicked allows the application to perform actions needed when a Font has been applied. This can include assigning the value in Font to another control. Similar actions need to be performed when the Execute method returns True, indicating that the OK button was clicked.

OnApplyClicked is signalled from the ApplyClicked method, and triggered directly from methods in widgetset classes.

A text snippet displayed as a preview for the selected font in the dialog.

PreviewText is a String property with a short snippet of text to display using the currently selected font in the dialog. It acts as a WYSIWYG preview mechanism.

Please note that use of PreviewText is dependent on platform / widgetset support. For instance, Windows does render PreviewText. It uses its own "Sample", and renders the font name in the selection list using the typeface. QT and QT5 have the same behavior as Windows. It is implemented for the GTK, GTK2 and MUI widgetsets.

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" radio button is selected. This option will be set when the user presses "Find Next" If set the "Match case" check box is hidden on the Find dialog. If set the "Whole word" check box is hidden on 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. If set the "Match case" check box is disabled on the Find dialog. If set the "Up" and "Down" radio buttons are disabled in the Find dialog. If set the "Whole word" check box is disabled on the Find dialog. This flag is set if only the first occurrence of the search string is to be replaced with the replace string. This flag is set if all occurrences of the search string are to be replaced with the replace string. This flag is set when the user checks the "Whole word" checkbox. If set the dialog will display a help button. This flag is set when the user checks the "Prompt on replace" checkbox. If set the "Prompt on replace" check box is hidden on the Find dialog. 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.

TFindDialog - a dialog used for finding text within the current editor or text buffer.

Opens a dialog box allowing the user to enter text for searching, for example in a text editor.

As TFindDialog is the parent class for the TReplaceDialog, it contains definitions for the Replace method, but the Replace option does not actually appear when the dialog is displayed: you need to use TReplaceDialog to do that.

FFindForm - local variable holding the form used for the Find dialog. FOnReplace - local variable identifying the event handler for replacing. FOnFind - local variable identifying the event handler for finding. FOptions - local variable holding the set of current options. FOnHelpClicked - local variable identifying the help event handler. FReplaceText - local variable holding the Replace text. FFindText - local variable containing the text to be found. 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. 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. 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. 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. 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. 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 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 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.

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. 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.

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. 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.

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 value in Options to [frDown]. It also stores the unassigned value (-1) for both the Left and Top properties in the class instance.

Owner of the class instance. 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.

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 configured and displayed in the method. 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 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 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.

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.

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.

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.

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.

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.

A number of buttons appear, offering the choice to replace this instance, find next, replace all.

Default value for the Title property used on the replace dialog. Returns the value in the rsReplace constant. ReplaceClick - code to execute when the Replace button is clicked (replace just the current instance). Object for the event notification. ReplaceAllClick - code to execute when the Replace All button is clicked (replace all remaining instances). Object for the event notification. Gets the form instance displayed when dialog is executed. TFindDialog.CreateForm Form instance with the editing controls and buttons used on the dialog form. Copies property values from the class instance to the controls on the dialog form. Copies property values from the dialog form to class instance after the dialog has been executed. Constructor for the class instance.

Create is the constructor for TReplaceDialog, and calls the inherited Create method. It sets the initial option values for find and replace.

TFindDialog.Create Owner of the class instance. Base class for TPrinterSetupDialog and TPageSetupDialog. Enumerated type which represents page ranges used in a print dialog. Print all pages. Print the selected range of pages. Print the selection of individual pages. Print the current page. Enumerated type with available options for a print dialog. Enables and checks the print to a file check box. Selects the Pages radio button in the dialog. Selects the Selection radio button in a print dialog. Displays a warning message for a print error. Displays a Help button in a print dialog. Disables the print to file check box in a print dialog. A set type used for the options in a print dialog. Implements the base class for TPrintDialog.

TCustomPrintDialog provides properties needed to configure print jobs in the TPrintDialog descendant.

Use the Options property to enable or disable use of specific properties on the dialog.

Use the Execute method to display the dialog and capture the values entered using the dialog. Use UserChoice to determine the button clicked or action taken to close the dialog.

The TPrintDialog descendant is defined in the printer4lazarus package.

Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited method on entry. Create sets the default values for the PrintRange and Copies properties.

Owner of the class instance. Enables or disables page collation when multiple copies are produced. Number of Copies requested for the document. First page number to include in the print request. Smallest value allowed in the page number for a print range. Largest value allowed in the page number for a print range. Set of options enabled when the print dialog is executed.

Options is a TPrintDialogOptions property with the options enabled for the print dialog. It can contain 0 (zero) or more values from the TPrintDialogOption enumeration. When a value is included in the set, the corresponding option is enabled when the Execute method is called.

Values in the property are used to configure the TPrintDialog descendant before it is displayed and executed. The values control both the properties and printer flags used in the print dialog.

See TPrintDialogOption for the values allowed in the set and their meanings.

The default value for the property is an empty set ([]).

When True, printing is spooled to a file instead of directly to the printer. Determines which values are used to represent the page range.

PrintRange is a TPrintRange property which indicates which values on the dialog are used for the page range in a print job.

prAllPages: Selects all pages in a document for the print job. This is the default value for the property.
prSelection: Causes the pages selected on the dialog to be used.
prPageNums: Causes the page range in the FromPage and ToPage properties to be used on the print dialog.
prCurrentPage: Causes the current page only to be printed.

ToPage - the final page number in the range for printing. Represents options that can be enabled for TTaskDialog. TTaskDialogFlag values are stored in the TTaskDialogFlags type, as used in the TCustomTaskDialog.Flags property. Modified in LCL 3.0 to include tfEmulateClassicStyle in the enumeration. Allows HTML-like hyperlinks in the dialog (in Text, Footer, and ExpandedText) using the '<a href="target">Target</a>' notation. Uses the handle to the image in MainIcon as the primary image for the Task dialog. Disables hyperlinks. Uses the handle to the image in FooterIcon as the footer icon in the Task dialog. Disables hyperlinks. Allow canceling the dialog by Esc key, or Alt+F4 (i.e. OS default hotkey). Custom buttons will be shown as big buttons in the middle of the dialog. Use #10 to add info to buttons (shown in hint in emulated dialog). Disables hyperlinks. Hides glyphs for custom buttons in the "command links" mode. Disables hyperlinks. Show ExpandedText in the footer, instead of inline after the main text. Displays the dialog with ExpandedText in the expanded state. Displays the verification check-box verification shows in the checked state. Shows a progress bar. Shows a progress bar using the marquee style. Execute the timer callback event every 200 milliseconds. Form position will be poOwnerFormCenter, instead of poScreenCenter. Use Right-to-Left layout for texts. Does not pre-select any of the radio buttons. Allow the dialog to be minimized. Forces use of an emulated task dialog form. Used to enforce conformity in the visual appearance of a dialog in an application which is not using a theme. Set type used to store values from the TTaskDialogFlag enumeration.

TTaskDialogFlags is the type used for the TCustomTaskDialog.Flags property.

Identifier used for common buttons visible on a Task dialog.

Values from TTaskDialogCommonButton are stored in the TTaskDialogCommonButtons set type, as used in the TCustomTaskDialog.CommonButtons property. When a value is included in the set, the corresponding button is visible on the task dialog.

The Ok button. The Yes button. The No button. The Cancel button. The Retry button. The Close button. Set type used to store values from TTaskDialogCommonButton.

TTaskDialogCommonButtons is the type used for the CommonButtons property in TCustomTaskDialog.

Specifies an event handler signalled when a button is clicked in TCustomTaskDialog / TTaskDialog.

TTaskDlgClickEvent is the type used for the OnButtonClicked event handler in TCustomTaskDialog.

Task dialog for the event notification. Modal result for the clicked button. True if the dialog can close. Identifier for an icon displayed on a Task dialog.

TTaskDialogIcon is the type used for the FooterIcon and MainIcon properties in TCustomTaskDialog.

No icon is displayed. Displays the Warning icon (Amber triangle with an Exclamation mark). Displays the Error icon (Red circle with an X). Displays the Information icon (Blue circle with a Question Mark). Displays the Shield icon. Displays the Question icon (Blue circle with a Question Mark). Defines the base class for a custom button displayed on a Task dialog.

TTaskDialogBaseButtonItem is a TCollectionItem descendant which defines a custom button that can be displayed on a Task dialog. It provides properties that indicate the Caption for the button, its use as the Default button on a dialog, and its ModalResult value.

TTaskDialogBaseButtonItem is the ancestor class for TTaskDialogBaseButtonItem.

TCustomTaskDialog where the button is used.

Client is a read-only TCustomTaskDialog property with the dialog where the button is used. Its value is set to the Task dialog that is the owner of the collection where the button definition is stored.

TCollection.Owner Gets the value for the DisplayName property.

GetDisplayName is an overridden method used to get the value for the DisplayName property. In TTaskDialogBaseButtonItem, the value in Caption is used (when assigned) for the property value. When Caption is empty, the inherited method is called to get the property value.

TCollectionItem Value for the DisplayName property. Gets the collection where the button definition is stored.

TaskButtonCollection is a TTaskDialogButtons function which retrieves the Collection where the button definition is stored. It allows the button definition to access properties and methods in the collection.

Collection which owns the button cast to a TTaskDialogButtons type. Constructor for the class instance.

Create is the overridden constructor for the class instance. It calls the inherited method on entry, and sets the value in the Client property to the dialog which is the owner for the Collection. The value in ModalResult is set to the ID value for the collection item + 100.

TCollectionItem.Collection TCollectionItem.ID Collection which owns the button item. Modal result value returned when the button is clicked.

The default value for the property is assigned when the button item is created and is based in its ID value + 100. The value can be changed to any reasonable value that is unique for the context.

ModalResult is used when a Task dialog is executed and a button is clicked on the dialog. Its value for the clicked button is assigned to the ModalResult property in the TCustomTaskDialog instance.

Caption text displayed on the button surface.

Caption is a TTranslateString property with the caption text displayed on the button surface. It can be localized using the built-in translation facilities available in the LCL. When assigned, Caption also provides the DisplayName for the collection item in the object inspector.

TCollectionItem.DisplayName Indicates if the button is the default button on a Task dialog.

Default is a Boolean property which indicates if the button is the default button for a Task dialog. The default value for the property is False.

Changing the value in the property causes the DefaultButton property in the Collection to be updated. When set to True, the button instance is assigned to the DefaultButton property in the collection. When set to False, the DefaultButton in the collection is set to Nil.

TCollectionItem.Collection Implements a button definition used for a button in TCustomTaskDialog.

TTaskDialogButtonItem is a TTaskDialogBaseButtonItem descendant used to define and store buttons created in TCustomTaskDialog / TTaskDialog. It provides an overridden constructor which creates an object inspector-friendly name for the button item. It also sets the visibility for the ModalResult property to published.

TTaskDialogButtonItem is the type used for the Button property in TCustomTaskDialog, and maintained in its Buttons collection.

Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited method on entry. It assigns an object inspector-friendly value to the Caption property, such as 'Button3'. The Caption is also used as the DisplayName for the collection item when assigned.

TCollectionItem.DisplayName Collection which owns the button item. Implements a radio button displayed on a Task dialog.

TTaskDialogRadioButtonItem is a TTaskDialogBaseButtonItem descendant which implements a radio button displayed on a Task dialog. TTaskDialogRadioButtonItem is the type used for the RadioButton property in TCustomTaskDialog, and maintained in its RadioButtons collection.

Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited method on entry. Creates assign an object inspector-friendly value for the Caption property, such as 'RadioButton2'.

Collection which owns the radio button item. Implements an enumerator for buttons defined in a Task dialog. Constructor for the class instance.

Sets the internal position for the enumerator to -1 to indicate that a button is not available. Use MoveNext to position the enumerator at the first button in the collection.

Collection which owns the buttons for the enumerator. Gets the value for the Current property. Value for the Current property. Positions the enumerator on the next button in the collection.

MoveNext is a Boolean function used to move the position for the enumeration to the next button in the collection. When the enumerator is created, its position is undefined (-1) by default. Use MoveNext to move the position to the first button when the enumerator is created.

The return value is True when another value was found in the collection. It is set to False if the position reaches the value in Count.

TCollection.Count True if another button was available in the collection. Button at the current position for the enumerator.

Current is a read-only TTaskDialogBaseButtonItem property with the button at the current position for the enumerator. It uses the ordinal position in the collection for the button item as set when the MoveNext method was called.

Collection type used to access and maintain buttons defined for a Task dialog.

TTaskDialogButtons is a TOwnedCollection descendant which implements the collection used for the buttons on a Task dialog. TTaskDialogButtons provides properties and methods used to access and maintain the buttons in the collection, such as: Add, FindButton, DefaultButton, Items, and GetEnumerator.

TTaskDialogButtons is the type used for the Buttons and RadioButtons properties in TCustomTaskDialog / TTaskDialog.

Adds a new collection item using the ItemClass for the collection.

Calls the inherited Add method to create the new collection item, and casts the return value to the TTaskDialogBaseButtonItem type used as the ItemClass. The inherited method uses the Collection as the Owner for the new collection item.

TCollection.Add TCollection.Owner TCollection.ItemClass Collection item created in the method. Gets the button item in the collection with the specified modal result value.

FindButton enumerates values in the Items property to find the first button using the modal result value in AModalResult. The return value is Nil if a button using the modal result value is not found.

TTaskDialogBaseButtonItem instance with the specified modal result value. Modal result value to locate in the button items for the collection. Gets an enumerator for the buttons in the Items property. TTaskDialogButtonsEnumerator instance for the buttons in the collection. Contains the collection item that is the default button for a Task dialog.

DefaultButton is a TTaskDialogBaseButtonItem property with the button that is the default button for a Task dialog. The value for the property is updated when the Default property in a button item is changed.

Provides indexed access to buttons defined in the collection.

Items is an indexed TTaskDialogBaseButtonItem property with the buttons defined for the collection. It re-implements the property introduced in the ancestor class to use the TTaskDialogBaseButtonItem type when reading or writing values in the collection. Values in the property are accessed by their ordinal position in the collection.

Items is the default property, and the target for an enumerator created for the class instance.

TCollection.Items TCollection.ItemClass Ordinal position in the collection for the property value. Defines a configurable, modal task dialog at run-time.

TCustomTaskDialog is a TComponent descendant which defines a configurable, modal task dialog. It is a non-visual component which creates modal dialogs at run-time, with rich UI elements. It is a wrapper for LCLTaskDialog.TTaskDialog which implements the Windows TaskDialog API.

TCustomTaskDialog provides properties which can be used to configure the class instance at design-time in the object inspector. At run-time, the Execute method handles converting properties and calling routines in the LCLTaskDialog.TTaskDialog implementation.

TComponent LCLTaskDialog.TTaskDialog Performs actions to configure and execute the dialog using the wrapper in the LCLTaskDialog unit.

DoExecute is a dynamic Boolean function used to initialize and execute the task dialog. It ensures that the index for the default Buttons and RadioButtons are updated before executing the task dialog. It also builds the delimited list of captions for each of the items in Buttons and RadioButtons. The lists use the format needed for the task dialog wrapper (#10 is the delimiter).

Property values are copied to the members in the TTaskDialog instance, including:

Caption
Title
Text
ExpandButtonCaption
ExpandedText
FooterText
VerificationText

DoExecute calls the Execute method in the TTaskDialog wrapper. The return value is True if the ModalResult value contains a valid button identifier defined in the Buttons for the dialog.

DoExecute is called from the Execute method.

TTaskDialog Modified in version 3.0 to use the tfForceNonNative flag to determine whether an emulated dialog is displayed. True if a valid button identifier was clicked in the dialog. Handle for the Parent Window of the dialog. Signals the OnButtonClicked event handler (when assigned) for the button with the specified modal result value.

DoOnButtonClicked is called from the callback routine passed to the wrapper in LCLTaskDialog.

Modal result value signalled for the button click notification. True if the dialog should be closed, or False to continue execution. Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited method on entry. Create allocates resources needed for the Buttons and RadioButtons properties. It sets the default values for the following properties:

CommonButtons: Set to the value [tcbOk, tcbCancel].
DefaultButton: Set to tcbOK.
Flags: Set to [tfAllowDialogCancellation].
FooterIcon: Set to tdiNone.
MainIcon: Set to tdiInformation.

Owner of the class instance. Destructor for the class instance.

Destroy is the overridden destructor for the class instance. It frees resources allocated for the Buttons and RadioButtons properties, and calls the inherited method prior to exit.

Displays the dialog and captures the modal result value.

Execute is an overloaded Boolean function used to display the dialog and capture the modal result value using the wrapper in the LCLTaskDialog unit. The return value is True if a valid button identifier was selected in the wrapper.

Execute calls the DoExecute method to convert property values in the class instance to the values expected in the TTaskDialog record, and execute the dialog using the LCLTaskDialog wrapper. The value in ModalResult is updated from the Button with the identifier returned from the wrapper.

TTaskDialog True if a valid button identifier was selected in the dialog. Parent window handle used to position the dialog in the LCLTaskDialog wrapper. Not used in the current LCL version.

Button is a TTaskDialogButtonItem property. It is not used in the current LCL version.

Collection with the buttons for the Task dialog.

Buttons is a TTaskDialogButtons property with the collection that contains the buttons for the Task dialog. Values in Buttons and CommonButtons are used in the DoExecute method to define the button identifiers and modal result values available in the LCLTaskDialog wrapper.

Caption text displayed on the title bar for the Task dialog.

Caption is a TTranslateString property with the text displayed on the title bar for the Task dialog. Caption can be localized using the LCL translation facilities.

Use Title to set the text displayed as the title in the main content area. Use Text to set the text displayed beneath the Title in the main content area. Use ExpandedText to set the text displayed in the expandable content area for the dialog. Use FooterText to set the text displayed in the footer aread for the dialog.

Set of common buttons displayed on the Task dialog.

CommonButtons is a TTaskDialogCommonButtons property with the set of common buttons displayed on the Task dialog. Values from the TTaskDialogCommonButton enumeration are included in the set to make buttons visible. Values are excluded from the set to remove the buttons. The default value for the property is [tcbOk, tcbCancel], and enables the OK and Cancel buttons for the Task dialog.

CommonButtons is used in conjunction with the Buttons collection, which contains custom button definitions that do not fit the common button definitions. Both CommonButtons and Buttons are used in DoExecute, and passed as arguments to the wrapper in LCLTaskDialog.

LCLTaskDialog.TTaskDialog Index of the default button, from the set in the CommonButtons property.

DefaultButton is TTaskDialogCommonButton property which indicates the default button for the Task dialog. It represents the button that is clicked if the user presses the Space or Enter key when the Task dialog is initially displayed.

The property contains one of the values from the CommonButtons property. The default value for the property is tcbOK, and represents the OK button.

It is used to set the default modal result value returned during execution when a DefaultButton has not been specified in the Buttons collection.

Caption displayed for the expand/collapse button on the dialog.

ExpandButtonCaption is a TTranslateString property with the caption text displayed beside the button used to expand or collapse the ExpandedText on the Task dialog. The property value can be localized using the standard LCL translation facilities.

The default value for the property is an empty String (''), and cause the values "See details" or "Hide details" to be used on the Task dialog (when the language is English). Setting a value for the property causes the same caption to be displayed for both the expanded and collapsed states; only the button indicator changes.

Use the Flags property to control the position (tfExpandFooterArea) or the expanded / collapsed state (tfExpandedByDefault) for the ExpandedText on the Task dialog.

TTranslateString Text that is displayed in the expandable / collapsible area on the Task dialog.

ExpandedText is a TTranslateString property with the text displayed in the expandable / collapsible area on the Task dialog. Its value can be localized using the standard LCL translation facilities. It can contain multi-line text when line ending characters (#13,#10) are embedded in the String value. For example:


ADialog.ExpandedText := 'Please read the Terms of Service.'+#10+
  'Available on our <a href="https://www.bogus.org/tos.html">Website</a>';

Or, the multi-line value can be entered in the object inspector property editor at design-time.

Text, ExpandedText, and FooterText allow an HTML-like hyperlinking capability (as seen in the previous code example). The feature must be enabled by including tfEnableHyperlinks in the Flags property. Use tfExpandFooterArea to control the position for the expanded text, or tfExpandedByDefault to expand or collapse the text area.

Multi-line property editors in the object inspector were enabled in Lazarus version 2.2.0. TTranslateString Set of options enabled for the Task dialog.

Flags is a TTaskDialogFlags property with the set of options for the Task dialog. It contains values from the TTaskDialogFlag enumeration, and when included, enable the corresponding feature in the Task Dialog. The default value for the property is [tfAllowDialogCancellation] and allows the dialog to be cancelled.

Icon for the footer area displayed at the bottom of the dialog.

FooterIcon is a TTaskDialogIcon property with a value which identifies the icon displayed in the footer area for the Task dialog. The footer icon is displayed beside the optional text in FooterText. The default value for the property is tdiNone, and causes the icon to be omitted. See TTaskDialogIcon for information about the values in the enumeration and their meanings.

Text that is displayed in the footer area on the Task dialog.

FooterText is a TTranslateString property with the text displayed in the footer area on the Task dialog. Its value can be localized using the standard LCL translation facilities. It can contain multi-line text when line ending characters (#13,#10) are embedded in the String value. For example:


ADialog.FooterText := '(c) Copyright 1960-2021, Acme Corporation LLC.' + #10 +
  'All rights reserved.';

Or, the multi-line value can be entered in the object inspector property editor at design-time.

Text, ExpandedText, and FooterText allow an HTML-like hyperlinking capability using the <a href="linktarget">Link Text</a> notation. The feature must be enabled by including tfEnableHyperlinks in the Flags property. Use tfExpandFooterArea to position the expanded text in the footer area.

Multi-line property editors in the object inspector were enabled in Lazarus version 2.2.0. TTranslateString Icon displayed beside the Title for the dialog.

MainIcon is a TTaskDialogIcon with a value that identifies the icon displayed beside the Title for the Task dialog. The default value is tdiInformation, and causes a blue circle with a Question Mark to be displayed as the icon. See TTaskDialogIcon for more information about the values in the enumeration and their meanings.

Modal result value returned when the Task dialog was executed.

ModalResult is a TModalResult property with the modal result value returned when the Task dialog was executed. It contains the corresponding value from the Button used to close the Task dialog, DefaultButton if Enter or Space was pressed when the dialog was displayed, or mrNone if the dialog was cancelled.

The radio button selected in the Task dialog.

RadioButton is a read-only TTaskDialogRadioButtonItem property with the radio button selected when the Task dialog was executed. The property value is set when the Execute method calls the wrapper in LCLTaskDialog. It contains an entry from the RadioButtons collection that was passed as an argument to the TTaskDialog wrapper.

Collection with the optional radio buttons defined for the Task dialog.

RadioButtons is a TTaskDialogButtons property with the collection of defined radio buttons for the Task dialog.

Radio buttons are displayed in the main content area for the Task dialog, below the values in Text and ExpandedText. Use of radio buttons is optional. They are displayed when items have been added to the collection. The TTaskDialogRadioButtonItem items in the collection are passed as an argument when the Execute method is called.

Use the RadioButton property to determine the radio button selected on the Task dialog.

Text displayed as main content for the Task dialog.

Text is a TTranslateString property with the text displayed in the main content area on the Task dialog. Its value can be localized using the standard LCL translation facilities. It can contain multi-line text when line ending characters (#13,#10) are embedded in the String value. For example:


ADialog.Text := 'Please read and accept the <a href="file://tos.pdf">Terms of Service</a>. '+
  #10+'You must agree before the application can be installed.';

Or, the multi-line value can be entered in the object inspector property editor at design-time.

Use ExpandedText to set the content in the collapsible area on the Task dialog. Use tfExpandFooterArea in the Flags property to position the expanded text in the footer area.

Multi-line property editors in the object inspector were enabled in Lazarus version 2.2.0. TTranslateString Header text displayed at the top of dialog, with a larger font size and using a bold font style. Sets the width in pixels for the task dialog form.

Width is an Integer property which sets the width (in pixels) for the task dialog form. The default value for the property is 0 (zero), and causes the width for the dialog form to be calculated when the dialog is executed using the length of its textual content.

Width is passed as an argument to the Execute method in the TTaskDialog instance used in the class.

Please note that an emulated task dialog form imposes a lower limit (120 pixels) or an upper limit (480 pixels) on the auto-calculated width.

TTaskDialog.Execute Optional caption text for the check box displayed at the bottom of the Task dialog. Event handler signalled for the button clicked when the Task dialog was executed.

OnButtonClicked is signalled after a button is clicked on the Task dialog.

Creates a configurable, modal task dialog at run-time.

A non-visual component which creates modal dialogs at run-time, with rich UI elements. Like the Windows TaskDialog API. For example:

Using TTaskDialog at Run-time.


procedure TForm1.Button1Click(Sender: TObject);
  var ATaskDialog: TTaskDialog; // requires Dialogs in uses clause
begin
  ATaskDialog := TTaskDialog.Create(Self);
  with ATaskDialog do
  begin
     Caption := 'Let''s do this...';
     MainIcon := tdiShield;
     Title := 'Task Title';

    Text := 'This tells the user the purpose for the dialog. ' +
      'Please read and accept the ' +
      '<a href="https://www.acme.org/tos.html">Terms of Service</a>. '+#10+#10+
      'Some users prefer a little conversation before they will agree. ' +
      'Along with a progress bar. Please tell us your level of interest.';

    RadioButtons.Clear;
    RadioButtons.Add.Caption := 'Low';
    RadioButtons.Add.Caption := 'Medium';
    RadioButtons.Add.Caption := 'High';

    CommonButtons := [tcbOk,tcbCancel,tcbRetry];

    ExpandedText := 'The Terms of Service grants a waiver of responsibility to ' +
      'Acme Corporation LLC (the Corporation) for any insane acts a Coyote ' +
      'might perform using products or services provided by the Corporation. '+#10+#10+
      'There is no legal venue where the Corporation is responsible. ' +
      'Especially Albuquerque, NM USA. ' +#10+#10+
      'Buyer beware. All rights reserved. Shipping fees and taxes may apply.';

    VerificationText := 'I agree to everything.';

    FooterIcon := tdiWarning;
    FooterText := 'This is your <a href="#terminus">final</a> warning.';

    Flags := [tfEnableHyperlinks, tfAllowDialogCancellation, tfExpandFooterArea, tfExpandedByDefault, tfVerificationFlagChecked, tfShowMarqueeProgressBar];

    if Execute then ; // do something with the ModalResult
    Free;
  end;
end;

Minimum width for a button on a dialog. Minimum height for a button on a dialog. Shows a message to the user and gets the response.

There are four versions of this function.

The first version displays a dialog with the standard caption. The second, third and fourth versions enable you to set the caption.

The third version allows for a Default button.

The fourth version contains a help keyword instead of using context-based help.

If the first Caption argument is missing, no caption is shown on the box.

This is the most complete and elaborate of the message dialogs, and allows the programmer considerable control over the appearance of the dialog box.

The arguments defining the kind of box and its icon are types rather than integer constants, and the buttons can be specified as a set in square brackets e.g. [mbRetry, mbIgnore, mbAbort, mbCancel].

The HelpCtx argument allows the use of Context Help

The return value from the Function is the identity of the button pressed, expressed as an integer (see the constant definitions in TControl , [mrNone..mrAll]).

If the user clicks the [X]-bordericon, the return value will be mrCancel.

If the user presses the escape key, the result depends on the widgetset:

If the widgetset has implemented a native dialog, the result will be mrCancel.
Otherwise the result will be mrCancel, mrNo or mrOk (in that order) when mbCancel, mbNo or mbOk is present. The dialog will not close when the Escape key is pressed if none of these buttons are present.

The result of this function is either the button the user pressed to close the dialog, or mrCancel.

The result of this function is the button the user pressed to close the dialog expressed as an integer.

If the user clicks the [X]-bordericon, the return value will be mrCancel.

If the user presses the escape key, the result depends on the widgetset:

If the widgetset has implemented a native dialog, the result will be mrCancel.
Otherwise the result will be mrCancel, mrNo or mrOk (in that order) if mbCancel, mbNo or mbOk is present. The dialog will not close when the Escape key is pressed if none of these buttons are present.

The message to be shown. The message shown to the user. The type of dialog to be shown.

The DlgType parameter indicates the type of dialog to show. You can choose from mtWarning, mtError, mtInformation, mtConfirmation or mtCustom.

Determines the buttons shown on the message dialog.

Buttons indicate which set of button captions have to be shown on the dialog. You can choose from predefined sets:

mbAbortRetryIgnore
mbOKCancel
mbYesNo
mbYesNoCancel

Or, you can make your own set.

HelpCtx is used to specify which topic from the help should be shown. HelpCtx is used to specify which topic from the help should be shown. Used to set the caption of the message dialog. Sets the caption of the message dialog shown by this function. The default button when the message dialog is executed. Help keyword for the message dialog. An extended MessageDlg function.

This function performs the same function as the MessageDlg function. It has been extended with parameters to place the dialog on a certain position on the screen instead of in the center of the screen.

The MessageDlgPos function does not enable you to choose the caption of the dialog.

The result of this function is either the button the user pressed to close the dialog, or mrCancel.

The result of this function is the button the user pressed to close the dialog expressed as an integer.

If the user clicks the [X]-bordericon, the return value will be mrCancel.

If the user presses the escape key, the result depends on the widgetset:

If the widgetset has implemented a native dialog, the result will be mrCancel.
Otherwise the result will be mrCancel, mrNo or mrOk (in that order) if mbCancel, mbNo or mbOk is present. The dialog will not close when the Escape key is pressed if none of these buttons are present.

The message to be shown. The message shown to the user. The type of dialog to be shown.

The DlgType parameter indicates the type of dialog to show. You can choose from mtWarning, mtError, mtInformation, mtConfirmation or mtCustom.

Determines the buttons shown on the message dialog.

Buttons indicate which buttons have to be shown on the dialog. You can choose from predefined sets:

mbAbortRetryIgnore
mbOKCancel
mbYesNo
mbYesNoCancel

Or, you can make your own set.

This function enables you to specify a Helpfile which has to be shown when the user presses F1.

The result of this function is either the button the user pressed to close the dialog, or mrCancel.

The result of this function is the button the user pressed to close the dialog expressed as an integer.

If the user clicks the [X]-bordericon, the return value will be mrCancel.

If the user presses the escape key, the result depends on the widgetset:

If the widgetset has implemented a native dialog, the result will be mrCancel.
Otherwise the result will be mrCancel, mrNo or mrOk (in that order) if mbCancel, mbNo or mbOk is present. The dialog will not close when the Escape key is pressed if none of these buttons are present.

The message to be shown. The message shown to the user. The type of dialog to be shown.

The DlgType parameter indicates the type of dialog to show. You can choose from mtWarning, mtError, mtInformation, mtConfirmation or mtCustom.

Determines the buttons shown on the message dialog.

Buttons indicate which buttons have to be shown on the dialog. You can choose from predefined sets:

mbAbortRetryIgnore
mbOKCancel
mbYesNo
mbYesNoCancel

Or, you can make your own set.

HelpCtx is used to specify which topic from the help should be shown. HelpCtx is used to specify which topic from the help should be shown. X specifies the position of the left side of the dialog. X specifies the position of the left side of the dialog Y specifies the position of the top side of the dialog. Y specifies the position of the top side of the dialog The Helpfile that has to be shown when the user presses F1 The name of the helpfile to be shown when the user presses F1 in the dialog. Creates a dialog form type with the specified caption, message, and buttons. TForm instance with the content representing the specified parameters. Message text for the dialog. Caption displayed as the title for the dialog. Identifies the dialog type and the image for the dialog. Set of TMsgDlgBtn buttons displayed on the dialog. Widgetset-independent implementation of a prompt dialog.

DefaultPromptDialog is a LongInt function which implements a widgetset-independent prompt dialog. It is uses a LCL TForm instance instead of relying on dialogs provided by the operating system. The content displayed on the dialog form is specified using the arguments passed to the routine, including:

DialogCaption: The caption for the dialog, displayed in the title bar for the dialog form. If Caption is an empty string (''), GetDialogCaption is called to get the default caption for the value in DialogType. The caption can be set to the Application title if DialogType is not one of the idDialogBase values.
DialogMessage: The text displayed inside the dialog as a prompt or message.
DialogType: A LongInt value which indicates the icon and default caption displayed for the dialog. It contains one of the constant values defined in the LCLType unit like: idDialogWarning, idDialogError, idDialogInfo, idDialogConfirm, or idDialogShield.
Buttons: Contains a pointer to an array of LongInt values which define the buttons displayed for the dialog. The values correspond to idButtonBase values defined in the LCLType unit like: idButtonOk, idButtonCancel, idButtonHelp, idButtonYes, idButtonNo, idButtonClose, idButtonAbort, idButtonRetry, idButtonIgnore, idButtonAll, idButtonYesToAll, or idButtonNoToAll. Buttons using the identifiers idButtonOpen, idButtonSave, and idButtonShield are not implemented in the current LCL version. The values for each of the buttons indicate the default icon and text for the button, as well as its modal result value.
ButtonCount: Contains the number of elements for the Buttons array.
DefaultIndex: Contains the ordinal position for the default button on the dialog. This is the button clicked when the Enter or the Space key is pressed during modal display of the dialog.
EscapeIndex: Contains the ordinal position for the button clicked when the Escape key is pressed during modal display of the dialog.
UseDefaultPos: Indicates if the dialog is displayed using the default position for the dialog form. When set to True, the value poDesigned is used in the Position property for the dialog form. When set to False, the values in the X and Y parameters are used in the Left and Top properties for the dialog form.

The return value contains the LongInt value returned for the button clicked on the dialog. It corresponds to the values passed in the Buttons argument, but may be changed to the value in EscapeIndex if the Escape key was pressed during dialog display.

The size and layout for elements on the dialog are calculated when the dialog form is created. The maximum width and height for the dialog is the largest space needed for the icon, message text and buttons on the dialog. For small-format devices (width is 300 pixel or less), a width of 200 pixels is used on the dialog form.

Example:


uses
  LCLType;

procedure TForm1.Button1Click(Sender: TObject);
var
  btns: array[0..2] of LongInt = (idButtonOK, idButtonCancel, idButtonHelp);
  res: LongInt;
begin
  res := DefaultPromptDialog('This is the caption',
    'This is the message of this dialog', idDialogInfo, @btns,
    3, 0, 1, true, 0, 0);
  Caption := 'Dialog result is ' + IntToStr(res);
end;

TCustomForm.ShowModal TCustomForm.ModalResult PromptDialogFunction LongInt value for the button clicked on the prompt dialog. Caption displayed on the dialog form. Text displayed as a prompt or message on the dialog form. Identifies the icon and default caption for the dialog. Contains the button identifiers displayed on the dialog form. Number of values in the Buttons argument. Position for the default button on the dialog form. Value returned when the Escape key is pressed for the dialog. True to use the default position for the dialog form, False to use the values in X and Y as the Top and Left coordinates. Horizontal coordinate where the dialog form is displayed. Vertical coordinate where the dialog form is displayed. Shows a question to the user and gets a response. Similar to MessageDlg, but allows to use custom button captions and user-specified response values.

QuestionDlg has the same functionality as MessageDlg except for the Buttons parameter which is of a different type. You can define your own captions, return values, and optional flags in Buttons using this function.

ACaption contains the text displayed as the title for the dialog form.

AMsg contains the text displayed within the content area for the dialog form. It represents the question to be answered using the dialog.

DlgType contains a value from the TMsgDlgType enumeration, and determines the icon displayed on the dialog form. See TMsgDlgType for the values in the enumeration and their meanings.

Buttons is defined as an array of const values, and contains the numeric identifiers and optional captions and flags for the buttons displayed on the dialog. QuestionDlg examines the values in Buttons, and creates a button instance for each numeric identifier in the array. Usually, the button identifiers are specified using TModalResult constants like mrOk or mrCancel (defined in ); these buttons will be decorated with an icon associated with the modal result value. Other integer values can be used as well, but their buttons will not have an icon. The order of the buttons on the dialog form will be the same as the order of the numeric values in the array elements.

Each string following a numeric button identifier denotes the caption for the button. When the button identifier is one of the default TModalResult values defined in controls.pp (mrNone..mrLast), the caption can be omitted and the default caption will be used. For non-TModalResult identifiers, the caption MUST be specified. An empty string is not allowed as a caption; it will raise a run-time error.

You can mark one button as the default button by adding the 'IsDefault' option after the caption string. When the user presses the Return key, this button is triggered. An exception is raised if more than one button has the 'IsDefault' designation.

Some widgetsets provide an Escape key and/or a close button for the dialog. This results in mrCancel in the return value, even if it is not in the given button list. Use the 'IsCancel' option after the caption string to cause the button to close the dialog. An exception is raised if more than one button has the 'IsCancel' designation.

You can use both 'IsDefault' and 'IsCancel' flags values for a given button by including both strings as arguments following the caption value. Values in button flags are case-insensitive; 'IsDefault' is considered the same as 'isdefault'.

The numeric identifier for the button clicked on the dialog is returned by the QuestionDlg() function.

The overloaded routines allow a help topic to be displayed when the F1 key is pressed. HelpCtx is the numeric identifier for the help topic passed as an argument to the AskUser routine in the widgetset. HelpKeyword is a string value that identifies the help topic. Please note that HelpKeyword is not implemented in the current LCL version; the numeric help context 0 is always used in the overloaded routine.

Examples:


var
  res: TModalResult;
//...

// OK, Cancel dialog using default button captions
res := QuestionDlg('Confirm', 'Delete all files and directories?', mtConfirmation,
  [mrOK, mrCancel], 0);
//...


// OK, Cancel dialog with custom button captions and accelerator keys
res := QuestionDlg('Confirm', 'Delete all files and directories?', mtConfirmation,
  [mrOK, '&Do it!', mrCancel, '&Nope'], 0);
//...

// custom modal result values and captions
res := QuestionDlg('Question', 'Is it Okay?', mtConfirmation,
 [400, 'Yes!!!', 401, 'Not cool', 402, 'My mistake'], 0);  
//...

// Yes, No, Cancel with custom captions and button flags
res := QuestionDlg('COPYING', 'Abort?', mtConfirmation,
  [mrNo,'&No', mrYes,'&Yes', mrCancel, '&Cancel', 'IsDefault', 'IsCancel'], 0);

case res of
  mrYes: ShowMessage('You clicked Yes');
  mrNo: ShowMessage('You clicked No');
else
  // mrCancel
  ShowMessage('You cancelled the dialog.');
end;

The result of this function is the identifier number for the button that the user pressed to close the dialog. Caption displayed as the title for the question dialog. Contains the question the user has to answer using the dialog. The type of dialog. It determines which icon is displayed on the dialog. An array of return values, captions and optional flags for the buttons on the question dialog. HelpCtx specifies the numeric identifier for the help topic shown when F1 is pressed. HelpKeyword specifies the help topic shown when F1 is pressed. The string argument is not used in the current LCL version, and the numeric HelpContext is always 0. Implements a widgetset-independent dialog similar to QuestionDlg.

DefaultQuestionDialog displays a message dialog, similar to QuestionDlg, but it uses a LCL TForm instance instead of relying on dialogs provided by the operating system. The content displayed on the dialog form is specified by the arguments passed to the routine, including:

aCaption: The title of the dialog, displayed in the title bar of the dialog form. In case of an empty string (''), the default caption of the dialog type (DlgType parameter) is selected, or, when the DlgType is not one of the idDialogXXX values the application title is used instead.
aMsg: The text of the message or question displayed in the dialog
DlgType: A LongInt value which defines the icon and default caption displayed for the dialog. It contains one of the constant values defined in the LCLType unit like: idDialogWarning, idDialogError, idDialogInfo, idDialogConfirm, or idDialogShield. Do not use the mtXXXX values used by other dialogs, they will produce the wrong icon.
Buttons: A collection of items representing the buttons shown in the dialog. Each item describes the button by its caption, an integer value which is returned by the function when this button is clicked, as well as boolean flags to identify the "Default" or "Cancel" button. The return value is typed TModalResult, but any other integers can be used as well. Be careful if you plan to use the idButtonXXX constants declared in the LCLType unit because they will assign the icons to the buttons differently. An empty caption string is NOT replaced by a default string here.
HelpCtx: Help context value for the help text to be displayed when the user presses F1.

Example

Since Buttons is a TCollection each item must be added individually:


var
  btns: TDialogButtons;  // requires "uses InterfaceBase"
  res: Integer;
...
  btns := TDialogButtons.Create(TDialogButton);
  with btns.Add do
  begin
    Caption := 'OK';
    ModalResult := mrOK;
  end;
  with btns.Add do
  begin
    Caption := 'Cancel now';
    ModalResult := mrCancel;
  end;
  with btns.Add do
  begin
    Caption := 'Ignore';
    ModalResult := mrIgnore;
  end;
  with btns.Add do
  begin
    Caption := 'Do it';
    ModalResult := 300;
    Default := true;
  end;

  res := DefaultQuestionDialog('This is the caption', 'This is the title', idDialogError, btns, 0);

This code will display a dialog box with the following four buttons:

'Ok' returning mrOk
'Cancel now' returning mrCancel
'Ignore' returning mrIgnore
'Do it' returning 300. This will be the default button (focused)

Returns the number value associated with each button. Title text of the dialog form Message text displayed in the dialog form. A number to select the icon shown in the dialog. Select one of the idDialogXXXX constants declared in the unit LCLType (idDialogWarning, idDialogError, idDialogInfo, idDialogConfirm or idDialogShield). Do not use the TMsgDlgType values which are used by other dialogs! A collection of button definitions with caption, return value when clicked, and boolean flags to identify the default and cancel button. HelpCtx specifies the help topic that should be shown when F1 is pressed. Displays the specified message text.

The simplest message dialog: takes a simple string as argument, displays it in a box, and waits for a mouse-click or enter-key event before returning to the calling routine or program.

This is a modal procedure call; the box is displayed, receives focus, and does not relinquish focus until the OK box is clicked or otherwise selected.

TApplication.MessageBox A string constant containing the message to be shown. A string constant containing the message to be shown. Shows a message assembled from a format string and an array of arguments.

This procedure is an extension to the ShowMessage procedure. The parameters it takes are the same as the Format function.

The format string. The parameters to be inserted in the message. Shows a message box at a given screen position. Shows a message box at a given screen position. A string constant which is the message to be shown. The horizontal position of the messagebox. The vertical position of the messagebox. Widgetset-independent implementation of a message box routine. MessageDlg Modal result value for the dialog which indicates the key pressed to close the message box. The message displayed in the message box. The caption or title for the message box. Indicates the buttons and icon displayed on the message box. Includes the combined values for message box button and icon constants defined in lcltype.pp. Displays a box with specified title and prompt, and accepts user input in a text box.

A default string can optionally be displayed in the text box. The user-entered or default string is returned as the function result.

If the user selects the OK button, the text in the text box is returned. If the user selects the Cancel button, the default string is returned.

The result of this function is the string the user entered in the editbox or the default string. The caption for the dialog box. The text asking the user for his input. Default value for dialog box. The value of the editbox in the dialog will have this value. Displays a Password prompt with input masking.

PasswordBox is a specialized form of InputQuery. The editbox on the dialog box will mask the input. The only parameters are aCaption and aPrompt.

Behaves very similarly to the InputQuery function with MaskInput set to True; the difference is that the password that was typed in is returned as the result of the function (like InputBox).

The string the user entered. The caption for the dialog. 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. Performs actions needed when a new instance of the form is created.

DoCreate is an overridden method in TCustomCopyToClipboardDialog. It calls the inherited method on entry to signal OnCreate or other create handler(s) (when assigned). DoCreate calls the RegisterDialogForCopyToClipboard routine to enable key preview and set the OnKeyDown handler for the form instance.

TCustomForm.OnCreate TCustomForm.DoCreate Specifies the method used to get the text for the message displayed on the dialog form.

GetMessageText is an abstract virtual method in TCustomCopyToClipboardDialog. It must be implemented in a descendent class to return the correct value for the dialog form implementation.

Text for the message displayed on the dialog form. Enables key preview and adds the OnKeyDown handler for the specified dialog. Dialog form instance updated in the routine. Copies the content from the specified dialog to the clipboard.

Content from the dialog is stored as text in the clipboard. No actions are performed in the routine if Key and Shift contain values for keys other than Ctrl+C or Ctrl+Ins. The clipboard will contain lines with the Caption and Message text for the dialog, as well as the captions (sans accelerator keys) for controls displayed on the dialog.

Dialog form instance examined in the routine. Not used in the routine. Virtual key code which initiated the operation. Shift, Ctrl, or Alt modifier for the key code. Input Query Edit size in pixels. Input Query Edit size as a percentage of the monitor width. Spacing between the controls on an Input Query dialog. List of options available when selecting a directory. Allows a new directory to be created in a select directory dialog. Indicates a directory that does not already exist should be created following execution of the dialog. Indicates the dialog should prompt the user for confirmation of the selected action. Set type used to store directory selection options.

TSelectDirOpts is a set type used to store zero or more values from the TSelectDirOpt enumeration. Values added to the set indicate the options enabled for a directory selection dialog. A TSelectDirOpts argument is passed to the SelectDirectory routine.

Specifies an event handler signalled when an InputQuery dialog is about to close. Object for the event notification. Array of values which can be displayed in the event handler. True if the InputQuery can be closed, False to continue execution of the dialog. A function that allows a user to select a directory.

This function will show a dialog which allows the user to select the required directory when the directory structure is displayed as a tree.

Under Windows the caption from the resulting dialog cannot be set, but the label above the directory tree will have this value.

There are two version of this function, the second one having the ability to indicate whether hidden folders should be shown as well.

A boolean indicating if the user pressed OK. A boolean indicating if the user selected a directory and pressed OK. A constant which sets the caption of the shown dialog. The directory the dialog should start in.

The directory the dialog should start in. If a valid directory is given, the selected directory in the tree will be set to this directory.

A variable which on exit contains the selected directory. A boolean constant indicating whether hidden folders should be shown too. Help context for the dialog. Set of options enabled for the dialog. Use InputQuery to show a dialog box to get input from the user.

Two versions of this function which displays a prompt and expects user input of textual data.

The first includes a MaskInput boolean argument which determines whether the user input is masked out by asterisks in the text-input box (like during entry of a password). The second variant omits this argument. Omitting the MaskInput argument is equivalent to setting it to False.

Value contains the initial text displayed in the edit control for the dialog. The text entered by the user is also returned in the variable argument Value.

The function result is a boolean which returns True if the OK button was pressed, or False if the box was closed by any other mechanism (such as clicking the 'Close' icon on the top title bar).

Another overloaded variant allows Arrays with String values to be passed in the APrompts and AValues arguments. They are used to create labels and edit controls on the dialog form, where the user can supply multiple values. The number of labels and edit controls on the dialog is determined by the length of the AValues array. An exception is raised when the APrompts and AValues arrays do not have the same length.

An event handler routine can be provided in the ACloseEvent argument to validate the input values, and determine if the dialog can be closed. It is signalled when the input dialog is closed by clicking the Cancel button or the Close icon on the dialog form. The handler returns an Array of String values input using the dialog.

Returns True of OK button was pressed, False if Cancel was pressed or abnormal exit. Result is True if the user pressed OK or hit RETURN in the dialog box. If the user pressed Cancel or the dialog was closed without pressing a button the result will be False. The caption for the dialog box. The text label displayed for the edit control on the dialog box. Determines if the dialog shows * characters instead of the actual input. Set MaskInput to True if you want to hide the input and display asterisks. The initial value(s) displayed, and the modified value(s) returned from the dialog box.

Value is a variable parameter used to pass the initial value(s) displayed in the dialog box. The overloaded variants allow Value to be specified using either a String or an Array of String type. Value is where the modified content from the dialog box is returned when the ENTER key is pressed or the OK button is clicked.

Array with strings values used as labels on the input dialog. Arrays with string values used in edit controls for the associated labels. Widgetset-independent implementation of an input dialog. InputDialogFunction True if the Ok button was clicked during execution of the dialog. Caption displayed as the title for the dialog. Label displayed on the dialog form. True if the edit control displays '*' characters to mask the input value. Default value for the edit control on the dialog, and the value entered at run-time. Creates and executes a combo-box dialog with the specified Caption, Prompt, and list of selectable values.

InputCombo is an Integer function used to create and display an input dialog with the values specified in the arguments to the routine.

The dialog form is constructed at run-time, and includes the controls needed to display the prompt (TLabel) and list of selectable items (TComboBox). It also includes a button panel (TButtonPanel) with Ok and Cancel buttons. The Caption for the dialog form is set to the ACaption argument.

The dimensions for the dialog form are determined by the maximum length of the string values passed in the function parameters. The form uses auto-scaling when enabled for the Application. Scaled size values are applied to the font for the form and its controls, as well the margins and separators used for control alignment. Anchors and BorderSpacing are used for control alignment to preserve their layout during auto-sizing and scaling operations. The display Position for the form is set to poScreenCenter.

InputCombo calls the ShowModal method for the TForm instance to display the dialog and capture the modal result value. When the modal result is mrOk (the OK button was pressed), the return value contains the ordinal position for the item in AList that was selected in the combo-box control. The return value is -1 when the Cancel button or the Close border decoration is clicked.

Use InputComboEx to display a dialog form that allows custom text to be entered in its combo-box control. Use InputQuery to display a dialog form which allows entry of a text value using an edit mask.

Ordinal position for the value selected in AList, or -1 if an option was not selected. Caption or title for the dialog. Label displayed for the combo-box control on the dialog. List of values which can be displayed and selected using the combo-box. Displays an extended input combo-box dialog that allows entry of custom text values in its Items.

InputComboEx is an overloaded String function used to create and display a dialog form that can select a value specified in the AList argument. The overloaded variants allow the AList argument to be specified as a TStrings instance or an array of String values.

ACaption contains the caption displayed as the title for the dialog form.

APrompt contains a string displayed as the label for the combo-box control.

AllowCustomText is a Boolean argument which indicates if text values can be added to the combo-box control at run-time. When set to True, text can be added to the TComboBox control. This is enabled by setting its Style property to csDropDown instead of csDropDownList (the default). The default value for the argument is False and prevents adding custom text to the combo-box control.

InputComboEx calls the ShowModal method for the TForm instance to display the dialog and capture the modal result value. When the modal result is mrOk (the OK button was pressed), the return value contains the value for the selected item in the combo-box control. The return value is an empty string ('') when the Cancel button or the Close border decoration is clicked.

String with the item selected in the combo-box, or an empty string if the dialog is cancelled. Caption for the dialog. Prompt or label for the combo-box control. List of values displayed in the combo-box control. True to allow new values to be added to the combo-box control. Extracts the color index and color value for the specified position in a color list. True on success, False if the list does not use the correct format. List of colors in COLORID=VALUE format. Position in the list for the extracted color index and value. Color index (ColorA=0, ColorB=1, etc.) TColor for the hexadecimal value in the list. Gets the resource string used as the caption for the specified dialog identifier.

The following dialog identifiers and return values are used in the routine:

idDialogWarning: Return value is rsMtWarning.
idDialogError: Return value is rsMtError.
idDialogInfo: Return value is rsMtInformation.
idDialogConfirm: Return value is rsMtConfirmation.
idDialogShield: Return value is rsMtAuthentication.

The return value is '?' when an unknown value is used in the idDiag argument.

Default caption for the dialog identifier. Identifier for the dialog type, i. e. idDialogWarning or idDialogError. Gets a bitmap with the icon for the specified dialog identifier.

The bitmap may contain a stock image provided by theme services (when available), or a PNG image image loaded from a Lazarus resource in the application.

Bitmap with the icon for the dialog identifier. Identifier for the dialog type, i. e. idDialogWarning or idDialogShield. Creates a formatted debugger message for one or more TOpenOption values. Formatted message with enumeration value name(s) for the option or options argument. TOpenOption enumeration value used to generate the formatted message. TOpenOptions set type with the options used to generate the formatted message. Registers components for use in the Lazarus IDE.

The following components are added to the Component Palette in the Lazarus IDE:

Dialogs Tab

TOpenDialog
TSaveDialog
TSelectDirectoryDialog
TColorDialog
TFontDialog
TFindDialog
TReplaceDialog
TTaskDialog

Misc Tab

TColorButton

RegisterComponents