From 811864db8174e27226cd86b59960590087b12548 Mon Sep 17 00:00:00 2001
From: dsiders <dsiders@lazarus-ide.org>
Date: Wed, 30 Oct 2024 02:14:31 +0100
Subject: [PATCH] Docs: LCL/forms. Updates TCustomForm.IconChanged topic for
 changes in 01640ee2. Issue #41189.

(cherry picked from commit 3325629775a1f27e6c5a53e5acca157f32c0f15a)
---
 docs/xml/lcl/forms.xml | 44 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 40 insertions(+), 4 deletions(-)

diff --git a/docs/xml/lcl/forms.xml b/docs/xml/lcl/forms.xml
index a5c7382e98..19e9617106 100644
--- a/docs/xml/lcl/forms.xml
+++ b/docs/xml/lcl/forms.xml
@@ -4209,12 +4209,48 @@ in the widgetset class.
 
 <element name="TCustomForm.IconChanged">
 <short>
-Loads the new form icons, and notifies the widgetset and all forms.
+Resets icon handle(s) for the form when CMIconChanged is called for the class 
+instance.
+</short>
+<descr>
+<p>
+<var>IconChanged</var> is a method used to to perform actions needed when the 
+CMIconChanged method is executed to handle a CM_ICONCHANGED message for the 
+form. It is assigned in the CreateNew constructor as the OnChange event handler 
+for the Icon property in the class instance.
+</p>
+<p>
+IconChanged recreates handles for icons used on the form instance. If the 
+handle for the form instance has been allocated, values in SmallIconHandle and 
+BigIconHandle are reset to the unassigned handle value (0). IconChanged calls 
+SetIcon in the widgetset class to send modified values to the widget. If the 
+form is the MainForm for the Application, or the form has a BorderStyle 
+<b>other than</b> bsDialog or bsNone, the values in SmallIconHandle and 
+BigIconHandle are sent to the widget. For form instances with a different value 
+in BorderStyle, the unassigned handle value (0) is used for both icon handles.
+</p>
+<p>
+Changing the value in BorderStyle or Icon at run-time causes IconChanged to be 
+performed for the form instance.
+</p>
+</descr>
+<seealso>
+<link id="TCustomForm.SmallIconHandle"/>
+<link id="TCustomForm.BigIconHandle"/>
+<link id="TCustomForm.Icon"/>
+<link id="TCustomForm.BorderStyle"/>
+<link id="TCustomForm.CreateNew"/>
+<link id="TApplication.MainForm"/>
+<link id="Application"/>
+<link id="#lcl.graphics.TIcon.OnChange">TIcon.OnChange</link>
+<link id="#lcl.controls.TWinControl.HandleAllocated">TWinControl.HandleAllocated</link>
+</seealso>
+</element>
+<element name="TCustomForm.IconChanged.Sender">
+<short>
+Object instance (TCustomForm) for the change notification.
 </short>
-<descr/>
-<seealso/>
 </element>
-<element name="TCustomForm.IconChanged.Sender"/>
 
 <element name="TCustomForm.DelayedEvent">
 <short>