From d43a2c62f2d52af63d3548929943db882dc99196 Mon Sep 17 00:00:00 2001 From: dsiders Date: Tue, 15 Aug 2023 18:45:28 +0100 Subject: [PATCH] Docs: LCL/taskdlgemulation. Adds missing topic content. (cherry picked from commit 28adff4a4bc9ec2159a964929dfdaff0b1069815) --- docs/xml/lcl/taskdlgemulation.xml | 355 ++++++++++++++++++++++++------ 1 file changed, 289 insertions(+), 66 deletions(-) diff --git a/docs/xml/lcl/taskdlgemulation.xml b/docs/xml/lcl/taskdlgemulation.xml index 331e1e8077..ac0ecf2d62 100644 --- a/docs/xml/lcl/taskdlgemulation.xml +++ b/docs/xml/lcl/taskdlgemulation.xml @@ -56,36 +56,91 @@ Added in LCL version 4.0 as replacement for the deprecated types in the - - - - + +Represents the textual display elements on a task dialog form. + + +

+TTaskDialogElement is an enumerated type with values which represent +the display areas for elements on an emulated task dialog form. Values in +TTaskDialogElement are used in the implementation of TLCLTaskDialog as an index +for TLabel instances used on the dialog form. +

+ + + + + - + +Content area which contains the text for the task dialog. + - + +Area with the expanded text for a task dialog. + - + +Area displayed at the bottom of a task dialog with the footer text and icon. + - + +Area with the title for a task dialog. + - + +Area used to display the query or simple query controls for a task dialog. + - + +Area used to display the check box with the verification text for a task dialog. + - - - - + +Implements an emulated (non-native) task dialog form. + + +

+TLCLTaskDialog is a TForm descendant which implements the +dialog form displayed when an emulated (non-native) TTaskDialog is +executed. It imitates the content, layout, and behavior for the dialog +displayed for the Windows Task Dialog API. +

+

+It provides support for use of TTaskDialog on platforms which do not implement +the Task Dialog API - including Windows versions prior to Windows Vista. Most +of the properties, methods, and members in the class are declared as private +and are available to the methods in the class instance. Application do not +normally create an instance of TLCLTaskDialog; it is created at run-time when +TTaskDialog calls its Execute method. +

+

+TLCLTaskDialog allows the dialog form to be configured at run-time using the +settings specified in the TTaskDialog passed as the Owner of the form. The +Execute methods handles initializing the form instance, displaying the dialog, +capturing the modal result value, and returning changes to the TTaskDialog for +the emulated task dialog form. +

+ + +Added in LCL version 4.0. + + + + + +TTaskDialog.Flags +TForm + @@ -100,7 +155,7 @@ Added in LCL version 4.0 as replacement for the deprecated types in the -The task dialog instance which created the dialog form. +The task dialog instance which created and is the owner of the dialog form. @@ -130,7 +185,7 @@ The task dialog instance which created the dialog form. -The labels corresponding to the Task Dialog main elements. +The labels corresponding to the Task Dialog display elements. @@ -501,38 +556,111 @@ the Name for the class. - Destructor for the class instance. - - + +

+Destroy is the overridden destructor for the class instance. It +ensures that the OnDialogDestroyed event handler in the TCustomTaskDialog +instance for the dialog form is signalled (when assigned). Destroy calls the +inherited destructor (in TCustomForm) prior to exit. +

+ + +TCustomTaskDialog.DoOnDialogDestroyed +TCustomForm.Destroy + - Performs actions needed when a new instance of the class has been created. - - + +

+AfterConstruction is an overridden method in TLCLTaskDialog used to +perform actions needed when the form instance has been created. It calls the +inherited method on entry to set the bounds for the form, signal the OnCreate +event handler (when assigned), and to perform scaling when enabled in both the +application and the form. +

+

+AfterConstruction signals the OnDialogConstructed event handler (when assigned) +in the TTaskDialog instance for the dialog form. +

+ + +TCustomTaskDialog.DoOnDialogConstructed +TCustomForm.AfterConstruction + - - - - + +Configures and displays the emulated task dialog and returns the modal result +value. + + +

+Execute is an Integer function used to configure, +display, and capture the modal result value for the emulated task dialog. The +return value contains the modal result for the button used to close the dialog +form. No actions are performed in the method when the Owner of the form has not +been assigned or is not a TTaskDialog instance. In this situation, the return +value is -1. +

+

+Execute calls the SetupControls method to configure and layout the elements on +the dialog form using the settings provided in the TTaskDialog instance. +

+

+AParentWnd contains the handle for the form that is used as the parent for the +dialog form. The value is compared to the handles for the forms on the current +Screen. When found, the form instance is assigned to the PopupParent property +for the dialog form. When not found, the currently active form on the screen is +used as the PopupParent. +

+

+Execute calls the ShowModal method (in TCustomForm) to manage modal display of +the dialog form in the application, and to start the processing loop for the +modal form. ShowModal sets the return value for the method. +

+

+When ShowModal has been completed, values from the updated form are applied to +the TTaskDialog instance which created the dialog. This includes values like: +

+
    +
  • The query result and query item index (when used).
    • +
  • The value from the simple query control (when used).
    • +
  • The verification check box state (when used).
    • +
  • +The identifier for the selected radio button returned in the ARadioRes argument. +
    • +
+ + +TTaskDialog.Flags + - + +Modal result value captured when ShowModal is called for the dialog form, or -1 +when the owner is not a TTaskDialog instance. + - + +Handle for the form which is the parent for the dialog form, or 0 to use the +active form on the screen. + - + +Returns the identifier for the selected radio button on the form, or 0 when not +available. + @@ -550,8 +678,8 @@ Performs actions needed when a new instance of the class has been created. -Variable with the function used to translate strings used on an emulated task -dialog instance. +Variable with the function used to translate strings on an emulated task dialog +instance. @@ -566,94 +694,187 @@ using translations unit. - - - + +Executes an emulated task dialog for using the specified arguments. + + +

+ExecuteLCLTaskDialog is an Integer function used to +execute an emulated task dialog form for the specified +TCustomTaskDialog instance. It is a convenience routine called from +the Execute method in the widgetset class instance for those platforms which do +not support the native Task Dialog API. +

+ - + +Modal result value captured when the emulated task dialog form is executed. + - + +TTaskDialog instance with the settings for the task dialog. + - + +Handle for the form which is the parent for the task dialog form. + - + +Returns the identifier for the selected radio button on the task dialog form. + - - - - + +Represents the available main icons for an emulated task dialog. + + +

+TLCLTaskDialogIcon is an enumerated type with values which represent +the icons available as the main icon on an emulated task dialog form. +

+ + + + +TTaskDialogIcon + - + +Indicates that an icon is not used on the dialog form. + - + +Represents the Warning icon. + - + +Represents the Question Mark icon. + - + +Represents the Error icon. + - + +Represents the Information icon. + - + +This value is not used. + - + +Represents the Shield icon. + - - - + +Represents the available footer icons for an emulated task dialog. + + +

+TLCLTaskDialogFooterIcon is an enumerated type with values which +represent the icons available as the footer icon on an emulated task dialog +form. +

+ - + +Indicates that a footer icon is not used. + - + +Represents the Warning icon. + - + +Represents the Question Mark icon. + - + +Represents the Error icon. + - + +Represents the Information icon. + - + +Represents the Shield icon. + - - + +

+IconMessage is a String function used to get the title +displayed on an emulated task dialog for the specified icon. It is used in the +implementation of TLCLTaskDialog to retrieve the title on the emulated task +dialog when the value has not already been assigned. The return value contains +the translated resource string associated with the index value in the Icon +argument. For example: +

+
+
tiWarning
+
Returns rsMtWarning.
+
tiQuestion
+
Returns rsMtConfirmation.
+
tiError
+
Returns rsMtError.
+
tiInformation, tiShield
+
Returns rsMtInformation.
+
Other values
+
Returns an empty string ('').
+
+

+IconMessage calls TD_Trans to localize the return value prior to exit. +

+ + + +TTaskDialogIcon + - + +Translated message content for the specified icon. + - + +Specifies the icon for the translated message. + - - + +Converts the specified TTaskDialogIcon main icon to the corresponding value in +the TLCLTaskDialogIcon enumeration. + @@ -664,9 +885,11 @@ using translations unit. - - + +Converts the specified TTaskDialogIcon footer icon to the corresponding value +in the TLCLTaskDialogFooterIcon enumeration. +