+ Create is the overridden constructor for the class instance, and calls the inherited method on entry. Create sets the default values for properties, including: +
++ The default value for the property is clBlack. +
++ ArrowType is a TArrowType property which indicates the direction for the arrow pointer on the control. The default value for the property is atLeft. Changing the value for the property causes the control to be redrawn. +
++ ArrowPointerAngle is an Integerproperty with the size of the angle (in degress) that forms the arrow pointer for the control. It determines the size in degrees for the angles on the base of the arrow pointer. ArrowPointerAngle must be in the range specified by the cMinAngle and cMaxAngle constants in the implementation for the control. The default value for the property is 60, and causes all three angles in the arrow pointer to measure 60 degrees. +
++ ArrowPointerAngle is used to calculate the points for the arrow pointer triangle. +
++ ShadowColor is a TColor property with the color used to draw the shadow on the control (when enabled). The default value for the property is cl3DShadow. Changing the value for the property causes the control to be redrawn. +
++ ShadowColor is used, along with ShadowType, in the Paint method to draw the triangle for the shadow on the control. The property value is used as both the pen and the brush color for the shadow triangle. +
++ DoAutoAdjustLayout is an overridden method used to apply the specified auto-adjust layout policy to the control. DoAutoAdjustLayout calls the inherited method on entry. +
++ DoAutoAdjustLayout ensures that the value in ColorRectWidth is adjusted by the scaling factor in AXProportion when AMode contains lapAutoAdjustWithoutHorizontalScrolling or lapAutoAdjustForDPI. The control is redrawn after ColorRectWidth is updated. +
++ DoAutoAdjustLayout is called from the AutoAdjustLayout method. +
++ FreeHandle is an overridden method in TControlCanvas. It calls the inherited method on entry to set the value in Handle to 0 (the unassigned value). If a device context (DC) has been allocated for the window handle (HWND), the ReleaseDC routine is called to release the device context. +
++ FreeHandle is called when a new value is assigned to the Control property, or when the class instance is freed. +
++ At run-time, the SetTempCursor method is called to apply the temporary cursor shape in the Cursor property. No actions are performed in the method at design-time. +
+
Visible is set to True by Show, or to False by Hide. Calling these methods is equivalent to setting the Visible property.
@@ -15392,7 +15442,7 @@ if MyControl.CanSetFocus then
+ DoOnParentHandleDestruction is overridden in TGraphicControl to re-implement the method in the ancestor class. It ensures that Handle for the Canvas is freed when the parent handler is destroyed. +
++ CMCursorChanged is an overridden method in TGraphicControl. It ensures that the control is Visible before the temporary cursor shape is changed. +
++ Visible must be set to True, and the Parent control (with the window handle) must be assigned before the control can be displayed. No actions are performed in the method if Visible is False, or Parent is Nil. +
++ In addition, the mouse must be over the control to apply the cursor shape using SetTempCursor and the value in the Cursor property. +
++ BeginUpdate is an overridden method in TDockTree. It increments the internal update counter for the class. It is used to consolidate calls to the UpdateAll method until the internal counter reaches zero (0). +
++ EndUpdate is an overridden method in TDockTree. BeginUpdate and EndUpdate are used to consolidate calls to the UpdateAll method. EndUpdate decrements the internal update counter, and when it reaches zero (0) calls UpdateAll to remove dtfUpdateAllNeeded from the docking tree flags. +
++ 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. +
+ 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. +
+ 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. +
++ TTaskDialogFlags is the type used for the TCustomTaskDialog.Flags property. +
++ 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. +
++ TTaskDialogCommonButtons is the type used for the CommonButtons property in TCustomTaskDialog. +
++ TTaskDlgClickEvent is the type used for the OnButtonClicked event handler in TCustomTaskDialog. +
++ TTaskDialogIcon is the type used for the FooterIcon and MainIcon properties in TCustomTaskDialog. +
++ TTaskDialogBaseButtonItem is a TCollectionItem descendant which defines a cusotm 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. +
++ 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. +
++ 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. +
++ 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. +
++ 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. +
++ 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 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. +
++ 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. +
++ 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. +
++ 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. +
++ 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. +
++ 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'. +
++ 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. +
++ 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. +
++ 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. +
++ 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. +
++ 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 metod uses the Collection as the Owner for the new collection item. +
++ 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. +
++ 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. +
++ 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. +
++ 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. +
++ DoOnButtonClicked is called from the callback routine passed to the wrapper in LCLTaskDialog. +
++ 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: +
++ 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. +
+
+ Execute is an overloaded Boolean function used to display the dialog and capture the modal result value using the wrapper in the
+ 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
+ Button is a TTaskDialogButtonItem property. It is not used in the current LCL version. +
+
+ 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
+ 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. +
++ CommonButtonsis a TTaskDialogCommonButtons property with the set of common buttons displayed on the Task dialog. Values from the TTaskDialogCommonButton enumeration are included in the set to make buttons visible. Values are excluded from the set to remove the buttons. The default value for the property is [tcbOk, tcbCancel], and enables the OK and Cancel buttons for the Task dialog. +
+
+ CommonButtons is used in conjunction with the Buttons collection, which contains custom button definitions that do not fit the common button definitions. Both CommonButtons and Buttons are used in DoExecute, and passed as arguments to the wrapper in
+ 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. +
++ ExpandButtonCaption is a TTranslateString property with the caption text displayed beside the button used to expand or collapse the ExpandedText on the Task dialog. The property value can be localized using the standard LCL translation facilities. +
++ The default value for the property is an empty String (''), and cause the values "See details" or "Hide details" to be used on the Task dialog (when the lanuguage is English). Setting a value for the property causes the same caption to be displayed for both the expanded and collapsed states; only the button indicator changes. +
++ Use the Flags property to control the position (tfExpandFooterArea) or the expanded / collapsed state (tfExpandedByDefault) for the ExpandedText on the Task dialog. +
++ ExpandedText is a TTranslateString property with the text displayed in the expandable / collapsable 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. +
++ 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. +
++ 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. +
++ 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. +
++ 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. +
+
+ 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
+ RadioButtons is a TTaskDialogButtons proprety 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 is a TTranslateString property with the text displayed in the main content area on the Task dialog. Its value can be localized using the standard LCL translation facilities. It can contain multi-line text when line ending characters (#13,#10) are embedded in the String value. For example: +
+
+ADialog.Text := 'Please read and accept the <a href="file://tos.pdf">Terms of Service</a>. '+
+ #10+'You must agree before the application can be installed.';
+
+ + Or, the multi-line value can be entered in the object inspector property editor at design-time. +
++ Text, ExpandedText, and FooterText allow an HTML-like hyperlinking capability using the <a href="linktarget">Link Text</a> notation. The feature must be enabled by including tfEnableHyperlinks in the Flags property. + Use tfExpandFooterArea to position the expanded text in the footer area. +
++ Use ExpandedText to set the content in the collasible area on the Task dialog. Use tfExpandFooterArea in the FLags property to position the expanded text in the footer area. +
++ OnButtonClicked is signalled after a button is clicked on the Task dialog. +
+- A non-visual component which creates modal dialogs at run-time, with rich UI elements. Like the Windows TaskDialog API. + 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;
+
- Show a message to the user and receive his response. There are four versions of this function. + 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. @@ -3643,7 +4138,7 @@ end;
[400, 'Yes!!!', 401, 'Are you mad?', 402, 'My mistake']
- This will create a dialog with three buttons; the captions of the buttons will be the strings given in the array. + This will create a dialog with three buttons; the captions for the buttons will be the strings values given in the array.
The return value of the function will be 400, 401 or 402, depending on whether the user clicked the 'Yes!!!', the 'Are you mad?' or the 'My mistake' button. @@ -3659,7 +4154,7 @@ end;
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.
@@ -3735,7 +4230,7 @@ end;
@@ -3767,7 +4262,7 @@ end;
PasswordBox is a specialized form of InputQuery. The editbox on the dialog box will mask the input. The only parameters are aCaption and aPrompt.
@@ -3852,7 +4347,7 @@ end;
This function will show a dialog which allows the user to select the required directory when the directory structure is displayed as a tree. @@ -4006,25 +4501,34 @@ end;
+ The following dialog identifers and return values are used in the routine: +
++ The return value is '?' when an unknown value is used in the idDiag argument. +
++ 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. +
+
Register is the procedure used to register components for use in the Lazarus IDE.
diff --git a/docs/xml/lcl/graphics.xml b/docs/xml/lcl/graphics.xml
index 7fbcfa24d5..794a2efbf7 100644
--- a/docs/xml/lcl/graphics.xml
+++ b/docs/xml/lcl/graphics.xml
@@ -11034,7 +11034,7 @@
+ GetResourceType is an overridden TResourceType function in TIcon.
+ It is used to get the resource type identifier for the class instance. It identifies the storage format used for graphic data in a resource.
+ The return value is RT_GROUP_ICON in TIcon.
+ TStringsSortCompare is an Integer function type used to compare string values to determine the relative sort order. The return value indicates the relative sort order for the compared items, and normally contains a value like the one returned from CompareText. For example:
+
+ The address for a TStringsSortCompare type is passed as an argument to the MergeSort routine.
+
+ MergeSort is an overloaded routine used to implement a comparison-based sort routine for values in List. List can be a TStrings or TFPList instance. No actions are performed in the routine when List has not been assigned (contains Nil).
+
+ The StartIndex and EndIndex arguments allow the intial and final entries in a TFPList instance to be specified. When the values are omitted, they default to the first value (position 0) and the last value (Count-1) in List.
+
+ OnCompare is the comparison routine used to detemine the order for the sorted values. It can be a TListSortCompare or TStringsSortCompare function, depending on the overloaded variant of the called routine.
+
+ MergeSort implements the J. von Nuemann divide-and-conquer algorithm, with an insertion sort used for lists with 6 or fewer elements.
+
+
+
+ DeleteAmpersands is an Integer function used to remove all occurences of the Ampersand character in Str. The return value contains the position in Str where the first occurence of the of the character was found. +
++ Double Ampersands (&&) are converted to a single & character in Str. +
++ DeleteAmpersands can be used to remove the prefix used for accelerator keys in button, tool bar, and menu captions. +
++ RemoveAmpersands is an overloaded function used to remove all occurences of a single Ampsersand (&) character from the specified value. It provides variants that operate on String and PChar types. The return value contains the original value after all single Ampersand characters have been removed. Double Ampersand (&&) characters are converted into a single Ampersand character. +
++ Use DeleteAmpersands to remove Ampersand character in the original String value. +
++ The return value contains the following: +
++ ComparePoints is an Integer function used to compare the coordinates in the specified TPoint instances to determine their relative order. The return value contains -1, 0, or 1 for the following conditions: +
++ See ComparePoints. +
++ Defined for platforms other than Windows. Needed because THandle in the RTL SysUtils unit is defined as longint. +
+