<?xml version="1.0" encoding="UTF-8"?>
<!--

Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus 
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0 
International public license.

https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/docs/cc-by-sa-4-0.txt

Copyright (c) 1997-2025, by the Lazarus Development Team.

-->
<fpdoc-descriptions>
<package name="lcl">
<!--
====================================================================
LCLClasses
====================================================================
-->
<module name="LCLClasses">
<short>
Defines the base class for all LCL TComponents including controls.
</short>
<descr/>

<!-- unresolved type references, used units -->
<element name="Classes"/>
<element name="WSLCLClasses"/>
<element name="WSReferences"/>
<element name="LCLType"/>
<element name="LCLProc"/>

<element name="LazLongRec">
<short>
Represents a Long value as low- and high-order signed SmallInt values.
</short>
<descr>
<p>
<file>SysUtils</file> has a <var>LongRec</var> structure which uses an 
unsigned <var>Word</var> type for <var>Lo</var> and <var>Hi</var>. 
<var>LazLongRec</var> provides a similar record with signed 
<var>SmallInt</var> members.
</p>
</descr>
<seealso></seealso>
</element>
<element name="LazLongRec.Lo">
<short>The low-order signed small integer value.</short>
</element>
<element name="LazLongRec.Hi">
<short>The high-order signed small integer value.</short>
</element>

<element name="TLCLComponent">
<short>
The base class for LCL components which have an associated widget.
</short>
<descr>
<p>
<var>TLCLComponent</var> is a <var>TComponent</var> descendant which is used 
as the ancestor for many components in the Lazarus Component Library 
(<b>LCL</b>), including:
</p>
<ul>
<li>TApplicationProperties</li>
<li>TCommonDialog</li>
<li>TControl</li>
<li>TCustomImageList</li>
<li>TCustomTrayIcon</li>
<li>TLCLReferenceComponent</li>
<li>TMenu</li>
<li>TMenuItem</li>
<li>TScreen</li>
</ul>
</descr>
<seealso>
<link id="TLCLReferenceComponent"/>
<link id="#rtl.classes.TComponent">TComponent</link>
</seealso>
</element>

<!-- private -->
<element name="TLCLComponent.FWidgetSetClass" link="#lcl.lclclasses.TLCLComponent.WidgetSetClass"/>
<element name="TLCLComponent.FLCLRefCount" link="#lcl.lclclasses.TLCLComponent.LCLRefCount"/>

<element name="TLCLComponent.WSRegisterClass">
<short>Registers this component class with the current WidgetSet.</short>
</element>

<element name="TLCLComponent.GetWSComponentClass">
<short>This method allows descendants to override the WidgetSetClass.</short>
<descr>
<p>
<var>GetWSComponentClass</var> is a <var>TWSLCLComponentClass</var> class 
function which allows descendants to override the <var>WidgetSetClass</var> 
class type used to create instances of the component. When WidgetSetClass has 
not been assigned (contains Nil), the return value is set to the 
<var>TWSLCLComponent</var> type.
</p>
</descr>
<seealso>
<link id="TLCLComponent.WidgetSetClass"/>
</seealso>
</element>
<element name="TLCLComponent.GetWSComponentClass.Result">
<short>Class type used to create instances of the specified component.</short>
</element>
<element name="TLCLComponent.GetWSComponentClass.ASelf">
<short>Component instance examined in the method.</short>
</element>

<element name="TLCLComponent.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the overridden constructor for the class instance. 
Create calls the inherited constructor. It also provides support for 
additional debugging information when <b>DebugLCLComponents</b> has been 
defined.
</p>
</descr>
<seealso/>
</element>
<element name="TLCLComponent.Create.TheOwner">
<short>Owner of the class instance.</short>
</element>

<element name="TLCLComponent.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the class instance. 
Destroy provides support for additional debugging information when 
<b>DebugLCLComponents</b> has been defined. Destroy calls the inherited 
destructor prior to exiting from the method.
</p>
</descr>
<seealso></seealso>
</element>

<!-- public -->
<element name="TLCLComponent.NewInstance">
<short>
Creates and registers a new instance of the class, and initializes the 
WidgetSetClass property.
</short>
<descr/>
<seealso>
<link id="TLCLComponent.WidgetSetClass"/>
</seealso>
</element>
<element name="TLCLComponent.NewInstance.Result">
<short>Class instance created in the method.</short>
</element>

<element name="TLCLComponent.RemoveAllHandlersOfObject">
<short>
Override this method to remove all references to notification handlers in 
AnObject.
</short>
<descr>
<p>
An override is required as soon as a component allows one to add notification 
handlers. Then all such handlers must be removed, when their owner (AnObject) 
is destroyed.
</p>
</descr>
<seealso/>
</element>
<element name="TLCLComponent.RemoveAllHandlersOfObject.AnObject">
<short>The object whose handlers shall be removed.</short>
</element>

<element name="TLCLComponent.IncLCLRefCount" link="#lcl.lclclasses.TLCLComponent.LCLRefCount"/>

<element name="TLCLComponent.DecLCLRefCount">
<short>
Decrements the reference counter for the LCL component.
</short>
<descr>
<p>
When the internal counter reaches 0, the FreeComponent method in the 
application is called to free resources allocated for the LCL component.
</p>
</descr>
<version>
Modified in LCL version 3.0 to signal the OnDecLCLRefcountToZero event in 
lclclasses.pas when the counter reaches 0.
</version>
<seealso>
<link id="TLCLComponent.LCLRefCount"/>
<link id="TLCLComponent.IncLCLRefCount"/>
<link id="#lcl.lclclasses.TLCLComponent.LCLRefCount">TLCLComponent.LCLRefCount</link>
</seealso>
</element>

<element name="TLCLComponent.LCLRefCount">
<short>The number of references to this component.</short>
<descr>
<p>
<var>LCLRefCount</var> is a read-only Integer property that contains the 
number of references to this component. The value in <var>LCLRefCount</var> 
is updated when the <var>IncLCLRefCount</var> and <var>DecLCLRefCount</var> 
methods are called while handling messages where the component instance is 
the target.
</p>
</descr>
<seealso>
<link id="#lcl.controls.TWinControl.IntfUTF8KeyPress">TWinControl.IntfUTF8KeyPress</link>
</seealso>
</element>

<element name="TLCLComponent.WidgetSetClass">
<short>The class type used to create instances of this component.</short>
<descr>
<p>
<var>WidgetSetClass</var> is a read-only <var>TWSLCLComponentClass</var> 
property which contains the class type used to create new instances of the 
component. The value for the property is set in the <var>NewInstance</var> 
method.
</p>
</descr>
<seealso>
<link id="TLCLComponent.NewInstance"/>
</seealso>
</element>

<element name="TLCLReferenceComponent">
<short>
Base class for all components having an associated widget with a handle.
</short>
<descr>
<p>
The widget is created by the LCL control whenever required, and its reference 
is stored in the FReferencePtr member. This reference is for internal use by 
the LCL control, and not by application code.
</p>
<p>
This reference is different from the OS/window manager-specific window Handle.
</p>
<p>
Applications only can send messages to a windowed control, using its window 
Handle.
</p>
</descr>
<version>
Modified in LCL version 4.0 to use the TLCLHandle type instead of the 
deprecated THandle type as the return value for the GetReferenceHandle method.
</version>
<seealso>
<link id="TLCLReferenceComponent.GetReferenceHandle"/>
<link id="TLCLReferenceComponent.ReferenceNeeded"/>
<link id="#lcl.WSReferences.TLCLHandle">TLCLHandle</link>
</seealso>
</element>

<!-- private -->
<element name="TLCLReferenceComponent.FReferencePtr">
<short>Pointer to a widget class Reference.</short>
</element>
<element name="TLCLReferenceComponent.FCreating">
<short>Set while we are creating the Reference.</short>
</element>

<element name="TLCLReferenceComponent.GetHandle"/>
<element name="TLCLReferenceComponent.GetHandle.Result"/>

<element name="TLCLReferenceComponent.GetReferenceAllocated">
<short>Gets the value for the ReferenceAllocated property.</short>
<descr></descr>
<seealso></seealso>
</element>
<element name="TLCLReferenceComponent.GetReferenceAllocated.Result">
<short>
Value for the ReferenceAllocated property.
</short>
</element>

<!-- protected -->
<element name="TLCLReferenceComponent.CreateParams">
<short>
Override this method to supply specific widget creation parameters.
</short>
</element>
<element name="TLCLReferenceComponent.CreateParams.AParams">
<short>The parameter record to update.</short>
</element>

<element name="TLCLReferenceComponent.DestroyReference">
<short>Destroys the reference object.</short>
</element>

<element name="TLCLReferenceComponent.GetReferenceHandle">
<short>Override this method to return the Handle from the reference.</short>
<seealso>
<link id="TLCLReferenceComponent.HandleAllocated"/>
</seealso>
</element>
<element name="TLCLReferenceComponent.GetReferenceHandle.Result">
<short>
<b>True</b> if both the component reference pointer and its Handle have been allocated.
</short>
</element>

<element name="TLCLReferenceComponent.ReferenceCreated">
<short>Called after the Reference is created.</short>
</element>

<element name="TLCLReferenceComponent.ReferenceDestroying">
<short>Called before the Reference is destroyed.</short>
</element>

<element name="TLCLReferenceComponent.ReferenceNeeded">
<short>
Creates the widgetset Reference for the class, if it has not already been 
allocated.
</short>
<seealso>
<link id="TLCLReferenceComponent.WSCreateReference"/>
<link id="TLCLReferenceComponent.GetReferenceHandle"/>
</seealso>
</element>

<element name="TLCLReferenceComponent.WSCreateReference">
<short>Tells the widgetset to create a Reference.</short>
<descr>
<p>
This implementation returns <b>Nil</b>, and should be overridden in derived 
classes.
</p>
</descr>
<seealso>
<link id="TLCLReferenceComponent.ReferenceNeeded"/>
</seealso>
</element>
<element name="TLCLReferenceComponent.WSCreateReference.Result">
<short>
Pointer to the reference for the widgetset class instance, or <b>Nil</b> when 
not allocated.
</short>
</element>
<element name="TLCLReferenceComponent.WSCreateReference.AParams">
<short>
Creation parameters for the reference.
</short>
</element>

<element name="TLCLReferenceComponent.WSDestroyReference">
<short>Tells the widgetset to destroy the Reference.</short>
</element>

<!-- public -->
<element name="TLCLReferenceComponent.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the class instance. 
Destroy calls <var>DestroyReference</var> to release an assigned internal 
reference for the widgetset class. Destroy calls the inherited destructor 
prior to exiting from the method.
</p>
</descr>
<seealso>
<link id="TLCLReferenceComponent.DestroyReference"/>
</seealso>
</element>

<element name="TLCLReferenceComponent.HandleAllocated" link="#lcl.lclclasses.TLCLReferenceComponent.ReferenceAllocated"/>

<element name="TLCLReferenceComponent.ReferenceAllocated">
<short>
If <b>True</b>, a Reference has been allocated for this component.
</short>
</element>

<element name="OnDecLCLRefcountToZero">
<short>
Event handler signalled when a reference counted LCL component is released.
</short>
<descr>
<p>
<var>OnDecLCLRefcountToZero</var> is a <var>TNotifyEvent</var> variable which 
contains the event handler signalled when reference counted TLCLComponent 
instances are released. It is signalled (when assigned) from the 
DecLCLRefCount method in TLCLComponent using the component instance as an 
argument.
</p>
<p>
The handler routine is assigned to the variable when the ReleaseComponent 
method is called in TApplication. It is set to the DoDecLCLRefcountToZero 
method in the Application. The routine will continue to be called until the 
LCLRefCount for the TLCLComponent reaches 0. At time, the handler is 
unassigned and FreeComponent is called.
</p>
</descr>
<verison>
Added in LCL version 3.0.
</verison>
<seealso/>
</element>

</module>
<!-- LCLClasses -->
</package>
</fpdoc-descriptions>