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

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. Enables multi-selection. 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.

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

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 the platform. Some options may not be available on a given platform. 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" 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" 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" checkbox is disabled in the Find dialog. If set the "Up" and "Down" radio buttons are disabled in the Find dialog. If set the "Whole word" checkbox is disabled in the Find dialog. 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. 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.

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.

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

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 any response values.

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 contains an array of integer identifiers and optional strings. For each number a button is created. Usually the identifiers are selected as the TModalResult constants [mrNone..mrYesLast] in ); the corresponding buttons will be decorated by an associated icon. Any other integers can be used as well, but their buttons will have no icon. The identifier number of the clicked button is returned by the QuestionDlg() function. The order of the buttons on the dialog form will be the same as the order of the array elements.

Each string following the button identifier in the Buttons array denotes the caption of 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. Empty strings are not allowed as captions, they will create a run-time error.

You can mark one default button by adding the 'IsDefault' option after the caption string. 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 after the caption string to redirect it to a button of your choice. You can combine 'IsDefault' and 'IsCancel'.

Example


var
  res: TModalResult;
...
  res := case QuestionDlg('COPYING', 'Abort?', mtConfirmation, [mrNo,'&No','IsDefault', mrYes,'&Yes'], 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 of the button that the user had 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, it determines which icon will be shown. An array of return values and captions 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 only of predefined return values like mrOK and mrCancel, the standard OK and Cancel buttons will be shown. The strength of this function, however, is that you can fill the array with arbitrary button identifiers and captions:

[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 after the numeric return values. 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 specifies the help topic that should be shown when F1 is pressed. HelpCtx specifies the help topic that should be shown when F1 is pressed. HelpKeyword specifies the help topic that should be shown when F1 is pressed. HelpKeyword specifies the help topic that should be shown when F1 is pressed. 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. 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. 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. 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. 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