diff --git a/docs/xml/lcl/dialogs.xml b/docs/xml/lcl/dialogs.xml index 12b5ce8614..a6c0e78cf5 100644 --- a/docs/xml/lcl/dialogs.xml +++ b/docs/xml/lcl/dialogs.xml @@ -1,6 +1,6 @@ - + + + + + + + + + + + + + @@ -100,6 +112,12 @@ + + + + + + @@ -108,6 +126,8 @@ Constants to define the types of message dialogs. + + @@ -122,6 +142,8 @@ Constants to define possible buttons on a dialog. + + @@ -132,7 +154,7 @@ - + @@ -150,44 +172,59 @@ Set of button messages for dialogs + + A "set" constant to show a Yes, a No and a Cancel button on a messagedialog. A "set" constant to show a Yes, a No and a Cancel button on a messagedialog. + A "set" constant to show a Yes and a No button on a messagedialog. A "set" constant to show a Yes and a No button on a messagedialog. + A "set" constant to show an OK and a Cancel button on a messagedialog. A "set" constant to show an OK and a Cancel button on a messagedialog. + A "set" constant to show an Abort, a Retry and an Ignore button on a messagedialog. A "set" constant to show an Abort, a Retry and an Ignore button on a messagedialog. + 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. + 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. + The base type from which other dialogs are derived Common Dialog: the base type from which all other dialogs are derived.
+ Use the "Create" method to make an instance of the dialog,
+ the "Execute" method to show it to the user
+ and the "Close" method to release it and free the used resources. + + @@ -243,6 +280,12 @@ and the "Close" method to release it and free the used resources. + + + + + + @@ -273,6 +316,9 @@ and the "Close" method to release it and free the used resources. The function that actually takes care of executing the dialog + + + @@ -287,6 +333,9 @@ and the "Close" method to release it and free the used resources. Create a new dialog + + + @@ -295,7 +344,10 @@ and the "Close" method to release it and free the used resources. A public method of a dialog showing the appropriate dialog. - Use the execute method of a dialog to show it
and then check the result to see if the user made a valid choice and pressed the OK button. + Use the execute method of a dialog to show it
+and then check the result to see if the user made a valid choice and pressed the OK button. + + @@ -316,14 +368,32 @@ and the "Close" method to release it and free the used resources. Close the dialog and return the memory used + + + the procedure that actually takes care of showing the dialog box + + + + + + + + + + + + The procedure that actually closes the dialog + + + @@ -380,6 +450,14 @@ and the "Close" method to release it and free the used resources. File Dialog File Dialog: allows selection of a file from the current directory. + + + + + + + + @@ -435,6 +513,12 @@ and the "Close" method to release it and free the used resources. + + + + + + @@ -444,12 +528,33 @@ and the "Close" method to release it and free the used resources. + + + + + + + + + Internal procedure called to execute the dialog. + + + + + + + + + + + + @@ -480,6 +585,9 @@ and the "Close" method to release it and free the used resources. Public method to create a FileDialog. + + + @@ -490,15 +598,27 @@ and the "Close" method to release it and free the used resources. + + + + + + + Public method which causes the dialog to be shown. + + + Stringlist which stored the selected files. + + @@ -506,31 +626,53 @@ and the "Close" method to release it and free the used resources. + + + + + + + + + Specifies the caption of the dialog. + + Property to set the default file extension for the file dialog box. + + String property to store the name of the file chosen by the user. + + A string property which contains possible filters. - 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 during runtime assign a value like: "All files|*.*|Lazarus Project files|*.lpr"
 + 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 during runtime assign a value like: "All files|*.*|Lazarus Project files|*.lpr"
 + Integer property setting the used file filter. - This property sets which file filter is the default. Set
this porperty to 2 to set the second filter as default. + This property sets which file filter is the default. Set
+this porperty to 2 to set the second filter as default. + Set the directory the dialog shows on opening. + + @@ -538,9 +680,17 @@ and the "Close" method to release it and free the used resources. + + + + + + A list of possible options which can be used in OpenDialog + + @@ -593,6 +743,8 @@ and the "Close" method to release it and free the used resources. Set of TOpenOption + + @@ -603,7 +755,10 @@ and the "Close" method to release it and free the used resources. Open Dialog - Open Dialog: open 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 Select Directory + Open Dialog: open 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 Select Directory + + @@ -639,26 +794,49 @@ and the "Close" method to release it and free the used resources. A protected function which checks if the chosen file meets all requirements. + + + + + + + + + + + + + + A protected method which calls CheckFile for each selected file. + + + Internal procedure called to execute the dialog. + + + Public method to create a OpenDialog + + + @@ -685,17 +863,25 @@ and the "Close" method to release it and free the used resources. 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. + 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. + 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. + Save Dialog - 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. + 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. + + @@ -710,18 +896,20 @@ and the "Close" method to release it and free the used resources. Select Directory Dialog Select Directory Dialog: allows the user to select a directory when the directory structure is displayed as a tree. + + - + - + - + @@ -736,15 +924,23 @@ and the "Close" method to release it and free the used resources. Colour Dialog Colour Dialog: presents a palette of colours to allow the user to select the required colour for text or graphics.
+ Call the Execute function to show the color dialog. + + Internal property to store the value of the chosen color. + + The method whoch create an instance of the TColorDialog. + + + @@ -752,16 +948,20 @@ Call the Execute function to show the color dialog. The caption for the color dialog. You can set the caption of the color dialog by changing this property. + A published property which reads en sets the FColor property When the Color dialog has been shown and the user pressed OK, the FColor property contains the chosen color. + Colour Button Colour Button: Pressing this button causes the Colour Dialog to be presented, allowing a choice of colour for text or graphics. + + @@ -770,6 +970,18 @@ Call the Execute function to show the color dialog. + + + + + + + + + + + + @@ -787,6 +999,15 @@ Call the Execute function to show the color dialog. + + + + + + + + + @@ -796,6 +1017,33 @@ Call the Execute function to show the color dialog. + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -804,28 +1052,53 @@ Call the Execute function to show the color dialog. - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -843,6 +1116,12 @@ Call the Execute function to show the color dialog. + + + + + + @@ -855,6 +1134,12 @@ Call the Execute function to show the color dialog. + + + + + + @@ -867,19 +1152,109 @@ Call the Execute function to show the color dialog. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -891,6 +1266,12 @@ Call the Execute function to show the color dialog. + + + + + + @@ -921,13 +1302,7 @@ Call the Execute function to show the color dialog. - - - - - - - + @@ -939,7 +1314,19 @@ Call the Execute function to show the color dialog. - + + + + + + + + + + + + + @@ -947,6 +1334,8 @@ Call the Execute function to show the color dialog. A set of constants to set the options of a Font dialog. + + @@ -990,6 +1379,8 @@ Call the Execute function to show the color dialog. Font Dialog Font Dialog: opens a dialog allowing choice of a font for textual displays + + @@ -1030,6 +1421,9 @@ Call the Execute function to show the color dialog. A private method which sets the font of the dialog. + + + @@ -1043,6 +1437,9 @@ Call the Execute function to show the color dialog. Public method to create a FontDialog. + + + @@ -1056,10 +1453,14 @@ Call the Execute function to show the color dialog. Specifies the caption of the dialog. + + Property to store the chosen font. + + @@ -1068,10 +1469,16 @@ Call the Execute function to show the color dialog. - + + + + + A set of options available from TFontDialogOptions + + @@ -1082,12 +1489,15 @@ Call the Execute function to show the color dialog. The text displayed in the preview pane of the dialog. - As a standard, the preview plane of the dialog
shows all letters both in uppercase and lowercase. + As a standard, the preview plane of the dialog
+shows all letters both in uppercase and lowercase. + A list of possible options which can be used in Find-dialogs. A list of possible options which can be used in Find-dialogs. + @@ -1144,6 +1554,592 @@ Call the Execute function to show the color dialog. A set of TFindOption + + + + + + 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
 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A dialog allowing the user to replace text + The dialog appears and offers boxes for the user to enter text for searching and text to replace it,
+for example while editing a file or large piece of text.
+ +A number of buttons appear, offering the choice to replace this instance, find next, replace all + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Base class for TPrinterSetupDialog and TPageSetupDialog. + + + + + + + Type of range of papers to print. + + + + + Print all pages. + + Print the selected range of pages. + + Print the selection of individual pages. + + Print the current page. + + + + + + + + + + + + + + + + + + + + + + + + + + + Base class for TPrintDialog. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -1151,41 +2147,54 @@ Call the Execute function to show the color dialog. Show a message to the user and receive his 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
+ eg [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]). + + The result of this function is the button the user pressed to close the dialog. - The result of this function is the button the user pressed to close the dialog.
This is expresed as an integer - - - - Used to set the caption of the messagedialog. - Sets the caption of the messagedialog shown by this function. + The result of this function is the button the user pressed to close the dialog.
+This is expresed as an integer @@ -1195,25 +2204,46 @@ expressed as an integer (see the constant definitions in 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. + 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 messagedialog - 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. + 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 messagedialog. + Sets the caption of the messagedialog 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 postion on the screen instead of in the centre of the screen. -
The MessageDlgPos function does not enable you to choose the caption of the dialog. + +function.
+It has been extended with parameters to place the dialog on a certain postion on the screen instead of in the centre of the screen. +
+The MessageDlgPos function does not enable you to choose the caption of the dialog. + + @@ -1228,12 +2258,20 @@ function.
It has been extended with parameters to place the dialog on a cer 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. + 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 messagedialog - 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. + 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. @@ -1254,6 +2292,8 @@ function.
It has been extended with parameters to place the dialog on a cer An extended MessageDlgPos function. This function enables you to specify a Helpfile which has to be shown when the user presses F1. + + @@ -1268,12 +2308,20 @@ function.
It has been extended with parameters to place the dialog on a cer 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. + 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 messagedialog - 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. + 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. @@ -1299,18 +2347,27 @@ function.
It has been extended with parameters to place the dialog on a cer Show a question to the user and get a response QuestionDlg has the same functionality as MessageDlg
+ except for the parameter Buttons which is of a different type.
+ You can define your own captions and return values of this function.

+ Buttons is a list of TModalResult (defined as constants [mrNone..MrYesToAll] in + ) and strings.
+ For each TModalResult a button is created.
+ To set a custom caption, add a string after a button.

+ The default TModalResults defined in controls.pp (mrNone..mrLast)
+ doesn't need a caption. The default captions will be used. + @@ -1338,36 +2395,55 @@ doesn't need a caption. The default captions will be used. An array of return values and caption for the buttons on the question dialog. - Buttons is defined as a array of const.
This means you can define any number of buttons to be shown.
If your array consists of only predefined return values like mrOK and mrCancel,
the standard OK and Cancel buttons will be shown.

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

-The strength of this function is however that you can fill the array like:
[400, 'Yes!!!', 401, 'Are you mad?', 402, 'My mistake'],
which will create a dialog with three buttons;
the captions of the buttons will be the strings given in the array.
-The return value of the function will be 400, 401 or 402,
depending on whether the user clicked the 'Yes!!!', the 'Are you mad?' or the 'My mistake' button. + +The strength of this function is however that you can fill the array like:
+[400, 'Yes!!!', 401, 'Are you mad?', 402, 'My mistake'],
+which will create a dialog with three buttons;
+the captions of the buttons will be the strings given in the array.
+ +The return value of the function will be 400, 401 or 402,
+depending on whether the user clicked the 'Yes!!!', the 'Are you mad?' or the 'My mistake' button. HelpCtx is used to specify which topic from the help should be shown. HelpCtx is used to specify which topic from the help should be shown. + + Show Message Procedure ShowMessage (const Msg: string);
+ The simplest message dialog: takes a simple string as argument,
+ displays it in a stereotyped 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,
+ that is the box is displayed, receives focus,
+ and does not relinquish focus until the OK box is clicked or otherwise selected.

 + @@ -1381,7 +2457,10 @@ and does not relinquish focus until the OK box is clicked or otherwise selected. 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. + + procedure. The parameters it takes are the same as the Format + function. + @@ -1396,6 +2475,7 @@ and does not relinquish focus until the OK box is clicked or otherwise selected. Shows a message box at a given screen position. Shows a message box at a given screen position. + @@ -1421,6 +2501,7 @@ and does not relinquish focus until the OK box is clicked or otherwise selected. 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).

Omitting the MaskInput argument is equivalent to setting it FALSE.

+ @@ -1448,7 +2529,9 @@ The function result is a boolean which returns TRUE if the OK button was pressed The value the user entered. - When the DialogBox is shown the text in the Editbox will be Value.
This string can be altered or amended by the user.
When ENTER is pressed or OK clicked, Value will be the (possibly amended) text from the Editbox. + When the DialogBox is shown the text in the Editbox will be Value.
+This string can be altered or amended by the user.
+When ENTER is pressed or OK clicked, Value will be the (possibly amended) text from the Editbox. @@ -1459,23 +2542,27 @@ The function result is a boolean which returns TRUE if the OK button was pressed

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 dialogbox - . + +. The text asking the user for his input - . + +. @@ -1486,8 +2573,13 @@ The function result is a boolean which returns TRUE if the OK button was pressed Password Box PasswordBox: a specialised form of the 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 = TRUE;
the difference is that the password that was typed in is returned as the result of the function (like InputBox). + +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 = TRUE;
+the difference is that the password that was typed in is returned as the result of the function (like InputBox). + @@ -1505,12 +2597,34 @@ The editbox on the dialog box will mask the input.
The only parameters are A prompt to ask for the users input. + + + + + + + + + + + + + + + + + + A function that allows to 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. + + @@ -1525,7 +2639,8 @@ There are two version of this function, the second one having the ability to ind 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. + 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. @@ -1537,23 +2652,17 @@ There are two version of this function, the second one having the ability to ind A boolean constant indicating whether hidden folders should be shown too. A boolean constant indicating whether hidden folders should be shown too. + + + + Register the components used in the current application, so that they can be recognised + + - - 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
 - - - - A dialog allowing the user to replace text - The dialog appears and offers boxes for the user to enter text for searching and text to replace it,
for example while editing a file or large piece of text.
-A number of buttons appear, offering the choice to replace this instance, find next, replace all - -