Contains common dialogs used in Lazarus LCL applications.

dialogs.pp contains classes, types, and routines used to implement common dialogs in an application. This file 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.
Set type used to store values from the TCDWSEventCapability enumeration.
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.
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.

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

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.

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. The default value for the property is provided by the DefaultTitle method, and assigned in the Create constructor.

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.

GetFilterIndex
- returns the Index value for the filename filter.
SetFileName
- specifies the filename in the file dialog.
SetFilter
- specifies the Filter for use in filename searching.
SetHistoryList
- specifies a list of strings that have been used in searching.
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.

DoTypeChange
- perform the code for the OnTypeChange event.
Stringlist which stores the names of the selected files.
HistoryList
- stringlist containing the names of files recently accessed.
IntfFileTypeChanged
- interface method for file type change.
Sets the default file extension for the file dialog box.
String storing the name of the file chosen by the user as UTF8

If you need the filename as system encoded, you can use UTF8ToSys from the unit FileUtil.

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

Set the directory the dialog shows on opening.
Event handler when the Help button is clicked.
Event Handler when the selected file type is changed.
Options which can be used in OpenDialog.

TOpenOption contains a list of possible options which can be used in an Open dialog.

If selected file exists shows a message, that file will be overwritten.
hide read only file.
do not change current directory.
show a help button.
allow multiselection.
shows an error message if selected path does not exist.
shows an error message if selected file does not exist.
do not return filenames that are readonly.
do not resolve links while dialog is shown (only on Windows, see OFN_NODEREFERENCELINKS).
do not resolve links after Execute.
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 used to store TOpenOption enumeration values.
Set constant with the default Open Dialog options.
Opens a file in the current directory, selected by File Dialog.

TOpenDialog opens a file in the current directory, selected by File Dialog. If the required file is not in the current directory, another directory can be selected with SelectDirectory.

Gets physical file names for file references or symbolic links.

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.

Resolves referential links.

Deprecated since LCL version 1.9. Use or override ResolveLinks instead.

Determines if the specified file name meets the requirements for the dialog.
CheckFileMustExist
returns True if a file with the specified name exists.
Calls CheckFile for each selected file, returns True if all are OK.
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.
DoFolderChange
- execute the code for a folder change.
DoSelectionChange
- execute the code for a change in selection.
Options to be used for this dialog.

Options to be used for the Open File dialog. A full list of available options is found in .

Event triggered when the user changes the folder in the OpenDialog.

This event is called when the user changes the folder (directory) in the OpenDialog.

Note: changing the folder will also trigger the OnSelectionChange event.

Event triggered when the user changes the selection made in the OpenDialog.

This event is triggered when the user changes the selected file in the OpenDialog.

Note: When the user changes the folder OnSelectionChange will be called first.

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

Save Dialog: invoked when the application requires to save a file.

If the file is already open or a filename has been specified, then the current buffer is written to that file. If no file is specified, the Save File As dialog is invoked and the buffer is saved to that file.

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 update the component style flags to the value used for the dialog type.

Owner of the class instance.
Select Directory Dialog.

SelectDirectoryDialog allows the user to select a directory when the directory structure is displayed as a tree.

TDirectoryEdit
TColorDialog
- dialog for selecting a color to use in graphics and text.

TColorDialog presents a palette of colors to allow the user to select the required color for text or graphics.

Call the Execute method to display the color dialog.

Internal member used to store the value for he selected color.
Internal member used to store user-specified colors.
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 destructor for TColorDialog, and frees custom colors then calls the inherited Destroy method.

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, which is an empty string in TColorDialog. Set the value for the property before calling the Execute method.

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 and may be 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.

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.

DrawGlyph
- draw the glyph on the button face.
GetDisabledPattern
returns a BitMap with a disabled pattern.
GetGlyphSize
returns a value with the size for glyphs on the button.
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 Color 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 initial bounds for the controls, as well as its size and pattern.

TCustomSpeedButton.create
Owner of the class instance.
Width for the borders on the button.
True if the button can be automatically re-sized.

ButtonColorAutoSize is a Boolean property which indicates if the button can be automatically re-sized.

ButtonColorSize
- the size of the button color block.
ButtonColor
- the color that has been selected by the ColorDialog and is displayed in the button.
The ColorDialog that opens when the button is activated.
Caption
- a string that can be placed beside the block of color.
The Color of the control itself, i.e. the parts that are not the color display block; edges, background etc.
OnColorChanged
- event handler for a change in button color.
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 strikethrough, underline, et. al. font effects in the dialog.
Limits the font name selection list to fixed-pitch (mono-spaced) fonts.
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.

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

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.

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.

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.
A list of possible options which can be used in Find-dialogs.
If set the "Down" radiobutton is selected.
This option will be set when the user presses "Find Next"
If set the "Match case" checkbox is hidden from the Find dialog.
If set the "Whole word" checkbox is hidden from the Find dialog.
If set the "Up" and "Down" radiobuttons are hidden from the Find dialog.
This flag is set when the user checks the "Match case" checkbox.
If set the "Match case" checkbox is disabled in the Find dialog.
If set the "Up" and "Down" radiobuttons are disabled in the Find dialog.
If set the "Whole word" checkbox is disabled in 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" checkbox is hidden from the Find dialog.
A set of TFindOption.
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.
FindClick
- method for execution when the Find button is clicked.
HelpClick
- method to execute when the Help button is clicked.
CancelClick
- method to execute when the Cancel button is clicked.
DoCloseForm
- execute the code for closing the Find/Replace dialog form.
Find
- software emulation of the OnFind event.
Help
- software emulation of the OnHelpClicked event.
Replace
- software emulation of the OnReplace event.
CreateForm
- function result returns the form that was created.
SetFormValues
- specifies the values for the form.
GetFormValues
- finds the values for the form.
ReplaceText
- the text string that is to be substituted for the Find text.
OnReplace
- event handler for replacing text.
Constructor for the class instance.

Create is the constructor for TFindDialog, and calls the inherited Create method. It sets the initial option values for Find only.

TComponent.Create TCommonDialog.Create
Owner of the class instance.
Destructor for the class instance.
CloseDialog
and returns its resources.
TCommonDialog.Execute
True if the dialog was successfully completed.
The Left side of the dialog display.
The Position of the dialog display.
the Top of the dialog display.
FindText
- the text string that the dialog will try to find.
The current Options for the seeking and replacing process.
OnFind
- event handler for a click on the Find button.
OnHelpClicked
- event handler for a click on the Help button.
A dialog allowing the user to replace text.

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.

ReplaceClick
- code to execute when the Replace button is clicked (replace just the current instance).
ReplaceAllClick
- code to execute when the Replace All button is clicked (replace all remaining instances).
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 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 for options in a print dialog.
TCustomPrintDialog
- base class for TPrintDialog.
Enables page collation when multiple copies are produced.
Number of Copies of the document.
FromPage
- first page of selection for printing.
MinPage
- smallest number of page in print range.
MaxPage
- highest number of page in print range.
The set of Options for printing.
When True, printing is spooled to a file instead of the printer.
PrintRange
- the range of pages for printing.
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.
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.
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 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 convert values in the class, and execute the dialog using the wrapper in the LCLTaskDialog unit.
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.

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.

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

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

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.

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.
Header text displayed at the top of dialog, with a larger font size and using a bold font style.
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.
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.

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
An extended MessageDlgPos function.

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.
PromptDialogFunction
Show a question to the user and get a response.

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

Buttons is a list of TModalResult (defined as constants [mrNone..MrYesToAll] in ) and strings. For each TModalResult a button is created. To set a custom caption, add a string after a button. You can use the special string parameters 'isdefault' and 'iscancel' to setup the default and cancel buttons.

The default TModalResults defined in controls.pp (mrNone..mrLast) don't need a caption. The default captions will be used.

You can mark one default button using the 'IsDefault' option. When the user presses 'Return' this button is triggered.

Some widgetsets provide an Escape key and/or a close button. This results in mrCancel even if it is not in the given button list. Use the 'IsCancel' option to redirect it to a button of your choice. You can combine 'IsDefault' and 'IsCancel'.

case QuestionDlg('COPYING', 'Abort?', mtConfirmation, [mrNo, '&No','IsDefault', mrYes,'&Yes'],0) 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 button the user pressed to close the dialog.
The result of this function is the button the user pressed to close the dialog.
Used to set the caption of the question dialog.
Set the caption of the question dialog shown by this function.
The question to be shown.
The question the user has to answer.
The type of dialog to be shown in fact which icon will be shown.
An array of return values and caption for the buttons on the question dialog.

Buttons is defined as a array of const. This means you can define any number of buttons to be shown. If your array consists of only predefined return values like mrOK and mrCancel, the standard OK and Cancel buttons will be shown.

The strength of this function is however that you can fill the array like:

[400, 'Yes!!!', 401, 'Are you mad?', 402, 'My mistake']

This will create a dialog with three buttons; the captions for the buttons will be the strings values given in the array.

The return value of the function will be 400, 401 or 402, depending on whether the user clicked the 'Yes!!!', the 'Are you mad?' or the 'My mistake' button.

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.
Implements a widgetset-independent dialog.

Shows a dialog with aCaption as Title, aMsg as Text, DlgType as Icon, HelpCtx as Help context and Buttons to define the shown buttons and their TModalResult.

Buttons is a list of TModalResult and strings. For each number a button is created. To set a custom caption, add a string after a button.

The default TModalResults defined in controls.pp (mrNone..mrLast) does not need a caption. The default captions will be used.

Examples for Buttons:

[mrOk,mrCancel,'Cancel now',mrIgnore,300,'Do it','IsDefault']

This will result in 4 buttons:

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

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

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.

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.
Registers components for use in the Lazarus IDE.

Register is the procedure used to register 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