diff --git a/docs/xml/lcl/dialogs.xml b/docs/xml/lcl/dialogs.xml index ee5153da82..5a4dbbce27 100644 --- a/docs/xml/lcl/dialogs.xml +++ b/docs/xml/lcl/dialogs.xml @@ -19,7 +19,9 @@ Dialogs ==================================================================== --> -Contains common dialogs used in Lazarus LCL applications. + +Contains common dialogs used in Lazarus LCL applications. +

dialogs.pp contains classes, types, and routines used to @@ -83,7 +85,9 @@ The following components are added to the Lazarus IDE component palette: Link to the topic content in system.uitypes when it exists in RTL.CHM. --> -Identifies the type or style for a message dialog. + +Identifies the type or style for a message dialog. +

TMsgDlgType is an alias to the TMsgDlgType enumerated @@ -5802,7 +5806,7 @@ TCustomTaskDialog is the base class for TaskDialog, and provides a multi-platform implementation of the Windows TaskDialog API. It provides properties which can be used to configure the task dialog at design-time or at run-time. At run-time, the Execute method handles converting -properties and calling routines and methods in the widgetset which implement +properties and calling routines and methods in the widgetset which implement the task dialog for a given platform.

@@ -6131,7 +6135,17 @@ State for the verification check box control on the dialog. Updates the value in URL and signals the OnHyperlinkClicked event handler (when assigned). - + +

+Called from the widgetset class instance when a hyperlink in Text, +ExpandedText, or FooterText is clicked. Use Flags to enable hyperlinks in the +text areas by including tfEnableHyperlinks in the property. +

+

+Use OnHyperlinkClicked to perform actions needed to handle the URL in the +hyperlink. +

+ Added in LCL version 4.0. @@ -6142,20 +6156,49 @@ Added in LCL version 4.0. -New value for the URL property. +New value for the URL property, and the target for the hyperlink. - - - + +Makes the radio button with the specified identifier the active RadioButton on +the task dialog. + + +

+SetRadioButtonFromRadioIndex is a method used to make the radio +button specified in AIndex the active (or default) RadioButton on +the task dialog. +

+

+AIndex is an Integer value which contains the button identifier for +the radio button (not its ordinal position) selected from the RadioButtons on +the dialog. The TTaskDialogButtons instance with the specified identifier is +stored in the RadioButton property. RadioButton may be set to Nil if +AIndex is not in the valid range for radio buttons starting at +TaskDialogFirstRadioButtonIndex, or RadioButtons does not contain the +identifier. +

+

+SetRadioButtonFromRadioIndex is called from methods like DoExecute and +DoOnRadioButtonClicked. +

+ Added in LCL version 4.0. - + + + + + + + + + @@ -6213,17 +6256,74 @@ exit. - - - - + +Gets the modal result value for the button with the specified identifier. + + +

+ButtonIDToModalResult is a TModalResult function used to +get the modal result value for the button with the identifier specified in the +AButtonID argument. +

+

+AButtonID contains one of the button identifier constants which correspond to +the standard Buttons used on the task dialog, including: +

+
    +
  • IDOK
    • +
  • IDCANCEL
    • +
  • IDABORT
    • +
  • IDRETRY
    • +
  • IDIGNORE
    • +
  • IDYES
    • +
  • IDNO
    • +
  • IDCLOSE
    • +
+

+If AButtonID is in the range of button identifiers starting at +TaskDialogFirstButtonIndex, but is not found in Buttons, the value in AButtonID +is used in the return value. If the identifier is valid for and found in +Buttons, the return value is set to one the modal result constants like: +

+
    +
  • mrOK
    • +
  • mrCancel
    • +
  • mrAbort
    • +
  • mrRetry
    • +
  • mrIgnore
    • +
  • mrYes
    • +
  • mrNo
    • +
  • mrClose
    • +
  • mrNone
    • +
+

+The return value is set to mrNone if AButtonID is not valid for or not found in +the Buttons collection. +

+

+ButtonIDToModalResult is called from the DoExecute method using the button +identifier returned from the Execute method in the widgetset class instance. +

+ + + + + + +TModalResult + - + +Modal result value for the button with the specified identifier. + - + +Numeric identifier for the button with the modal result value returned in the +method. + @@ -6272,7 +6372,9 @@ used in the current LCL version. -Collection with the buttons for the Task dialog. + +Collection with the buttons for the Task dialog. +

Buttons is a TTaskDialogButtons property with the @@ -6412,8 +6514,8 @@ ADialog.ExpandedText := 'Please read the Terms of Service.'+#10+ 'Available on our Website.';

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

Text, ExpandedText, and FooterText allow an HTML-like hyperlinking capability @@ -6442,15 +6544,22 @@ 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 using the Esc key or Alt+F4 key combination. +options enabled for the Task dialog. It contains zero or more values from the +TTaskDialogFlag enumeration, which when included, enable the corresponding +features in the Task Dialog. The default value for the property is +[tfAllowDialogCancellation] and allows the dialog to be cancelled using the Esc +key or Alt+F4 key combination.

-Changing the property values causes validation and normalization of the flag -values to be performed. tfQuery or tfSimpleQuery values are excluded from the -new property value if the value is already present in the property. +Changing the property value causes validation and normalization of the flag +values to be performed. tfQuery and tfSimpleQuery are mutually exclusive +values; if both are specified in the property value, then tfSimpleQuery is +excluded from the new property value. In addition, hyperlinks +(tfEnableHyperlinks) are disabled when tfQuery is included in the property. +

+

+See TTaskDialogFlag for the complete list of +enumeration values allowed in the property and their meanings.

@@ -6492,12 +6601,12 @@ 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.'; +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. +Or, the multi-line value can be entered in the object inspector using the +property editor at design-time.

Text, ExpandedText, and FooterText allow an HTML-like hyperlinking capability @@ -6562,7 +6671,6 @@ dialog was displayed, or mrNone if the dialog was cancelled. - Predefined values for the query control on the task dialog. @@ -6570,24 +6678,47 @@ Predefined values for the query control on the task dialog.

QueryChoices is a TStrings property with a list of -predefined values that can be selected in the query control for the task -dialog. +predefined values that can be selected in the query control on the task +dialog. Values in QueryChoices are displayed in a TComboBox control created for +the task dialog when tfQuery has been included in the Flags property. Include +tfQueryFixedChoices in Flags to make the values in QueryChoices read-only in +the combo-box control. +

+

+Use QueryItemIndex to determine which value is initially selected in +QueryChoices, or returned when the task dialog was executed.

Added in LCL version 4.0. - + + + + + + + - + +Ordinal position for the value in QueryChoices selected when the task dialog +is executed. + Added in LCL version 4.0. - + + + + + + + + @@ -6597,19 +6728,28 @@ Added in LCL version 4.0. Added in LCL version 4.0. - + + + + + + + + + -The radio button selected in the Task dialog. +The radio button selected on 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. +wrapper in LCLTaskDialog. +It contains an entry from the RadioButtons collection that was +passed as an argument to the TTaskDialog wrapper.

@@ -6664,8 +6804,15 @@ Added in LCL version 4.0. - - + +Character value used to obfuscate text entered in the query control. + + +

+The default value for the property is #0 (NULL character) and indicates that +obfuscation is not enabled for the simple query control. +

+ Added in LCL version 4.0. @@ -6689,8 +6836,8 @@ ADialog.Text := 'Please read and accept the Terms of Service. ' + #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. +Or, the multi-line value can be entered in the object inspector using the +property editor at design-time.

Text, ExpandedText, and FooterText allow an HTML-like hyperlinking capability @@ -6776,7 +6923,7 @@ pixels) or an upper limit (480 pixels) on the auto-calculated width. -Universal Resource Locator or identifier for a hyperlink clicked on the task +Universal Resource Locator (or identifier) for a hyperlink clicked on the task dialog. @@ -6837,7 +6984,10 @@ OnButtonClicked is signalled after a button is clicked on the Task dialog. - + +Event handler signalled after the constructor for the dialog form has been +called. + Added in LCL version 4.0. @@ -6867,7 +7017,10 @@ Added in LCL version 4.0. - + +Event handler signalled when the verification check box has been clicked on the +task dialog. + Added in LCL version 4.0. @@ -6903,7 +7056,8 @@ Added in LCL version 4.0. -Event handler signalled to update a progress bar on the task dialog. +Event handler signalled when the interval for the timer on the dialog has +elapsed.

@@ -6925,8 +7079,8 @@ Event handler signalled when a radio button on the dialog has been clicked.

-TNotifyEvent is a TNotifyEvent property with the event handler signalled when -a radio button on the task dialog has been clicked. +OnRadioButtonClicked is a TNotifyEvent property with the +event handler signalled when a radio button on the task dialog has been clicked.

@@ -6993,9 +7147,9 @@ begin 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+ + ExpandedText := 'The Terms of Service grants a waiver of responsibility '+ + 'to Acme Corporation LLC 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.'; @@ -7003,11 +7157,11 @@ begin VerificationText := 'I agree to everything.'; FooterIcon := tdiWarning; - FooterText := 'This is your <a href="#terminus">final</a> warning.'; + FooterText.Text := 'This is your <a href="#terminus">final</a> warning.'; Flags := [tfEnableHyperlinks, tfAllowDialogCancellation, tfExpandFooterArea, tfExpandedByDefault, tfVerificationFlagChecked, tfShowMarqueeProgressBar]; - if Execute then ; // do something with the ModalResult + if Execute then ; // do something based on ModalResult Free; end; end; @@ -7443,7 +7597,7 @@ 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 +unit like: idDialogWarning, idDialogError, idDialogInfo, idDialogConfirm, or idDialogShield.
@@ -7578,7 +7732,7 @@ allows to use custom button captions and user-specified response values.

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

@@ -8407,7 +8561,7 @@ dialog box.

-Value is a variable parameter used to pass the initial value(s) +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