From 901b01e6023b72062d3559f1e388548be50492b3 Mon Sep 17 00:00:00 2001
From: dsiders <dsiders@lazarus-ide.org>
Date: Tue, 6 Dec 2022 06:01:40 +0000
Subject: [PATCH] Docs: LCL/stdctrls. Updates TextHint topics in
 TCustomComboBox and TCustomEdit.

---
 docs/xml/lcl/stdctrls.xml | 79 +++++++++++++++++++++++++++++++--------
 1 file changed, 63 insertions(+), 16 deletions(-)

diff --git a/docs/xml/lcl/stdctrls.xml b/docs/xml/lcl/stdctrls.xml
index ebc9b9843b..5381e37798 100644
--- a/docs/xml/lcl/stdctrls.xml
+++ b/docs/xml/lcl/stdctrls.xml
@@ -4147,21 +4147,47 @@ other platforms / widgetsets.
 
 <element name="TCustomComboBox.TextHint">
 <short>
-Default hint text shown when the Text property is empty and the control is 
-not focused.
+Default hint text shown when the Text property is empty for the control.
 </short>
 <descr>
 <p>
 <var>TextHint</var> is a <var>TTranslateString</var> property which contains 
-the inline hint text displayed for the control. TextHint is displayed in the 
-editable area for the control when <var>Text</var> is an empty string 
-(<b>''</b>) and the control is not focused. As a TTranslateString value, it 
-can be translated using the LCL localization mechanism when enabled for the 
-project.
+the inline hint text displayed for the control. It is displayed in the 
+editable area for the <var>TCustomComboBox</var> when the Text property is 
+empty. Some platforms may refer to this feature as a "placeholder" or "editing 
+hint". As a TTranslateString value, it can be translated using the LCL 
+localization mechanism when enabled for the project.
+</p>
+<p>
+The value in TextHint is normally displayed using the color in clGrayText.
+</p>
+<p>
+The display behavior for TextHint is platform-specific. On some platforms, the 
+text hint is displayed any time the value in Text is empty. For others, it is 
+displayed only when the control does not have focus.
+</p>
+<p>
+Setting a new value in TextHint causes the widgetset class to be notified, 
+and the value is displayed in the edit control when allowed. If the new 
+property value is an empty string (''), the text hint is removed from the 
+control.
+</p>
+<p>
+For platforms that do not provide native support for TextHint, an emulated 
+text hint is displayed. This is a TCustomEdit control created to enable the 
+feature, and can be displayed only when the original control does not have 
+focus.
+</p>
+<p>
+TextHint is different than Hint, which displays a balloon tip when ShowHint is 
+set to <b>True</b> and the mouse is over the control.
 </p>
 </descr>
 <seealso>
 <link id="TCustomComboBox.Text"/>
+<link id="TCustomComboBox.CanShowEmulatedTextHint"/>
+<link id="#lcl.controls.TControl.Hint">TControl.Hint</link>
+<link id="#lcl.controls.TControl.ShowHint">TControl.ShowHint</link>
 </seealso>
 </element>
 
@@ -8294,23 +8320,44 @@ the control.
 
 <element name="TCustomEdit.TextHint">
 <short>
-Default hint text shown when the Text property is empty and the control is 
-not focused.
+Default hint text shown when the Text property is empty for the control.
 </short>
 <descr>
 <p>
-<var>TextHint</var> fills the <var>TCustomEdit</var> with the value in the 
-property when the Text in the control is empty and the control does not have 
-focus. This is different than Hint, which displays a balloon tip when 
-ShowHint is set to <b>True</b> and the mouse is over the control.
+<var>TextHint</var> is a <var>TTranslateString</var> property which contains 
+the inline hint text displayed for the control. It is displayed in the 
+editable area for the <var>TCustomEdit</var> when the Text property is empty. 
+Some platforms may refer to this feature as a "placeholder" or "editing hint". 
+The value in TextHint is normally displayed using the color in clGrayText.
+</p>
+<p>
+The display behavior for TextHint is platform-specific. On some platforms, the 
+text hint is displayed any time the value in Text is empty. For others, it is 
+displayed only when the control does not have focus.
 </p>
 <p>
 Setting a new value in TextHint causes the widgetset class to be notified, 
-and the value is displayed in the edit control when allowed. If the new value 
-is an empty string (''), the text hint is removed from the control.
+and the value is displayed in the edit control when allowed. If the new 
+property value is an empty string (''), the text hint is removed from the 
+control.
+</p>
+<p>
+For platforms that do not provide native support for TextHint, an emulated 
+text hint is displayed. This is a TCustomEdit control created to enable the 
+feature, and can be displayed only when the original control does not have 
+focus.
+</p>
+<p>
+TextHint is different than Hint, which displays a balloon tip when ShowHint is 
+set to <b>True</b> and the mouse is over the control.
 </p>
 </descr>
-<seealso/>
+<seealso>
+<link id="TCustomEdit.Text"/>
+<link id="TCustomEdit.CanShowEmulatedTextHint"/>
+<link id="#lcl.controls.TControl.Hint">TControl.Hint</link>
+<link id="#lcl.controls.TControl.ShowHint">TControl.ShowHint</link>
+</seealso>
 </element>
 
 <element name="TMemoScrollbar">