<?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">
<!--
====================================================================
CustomTimer
====================================================================
-->
<module name="CustomTimer">
<short>
Contains the definition of the base class for <var>TTimer</var>.
</short>
<descr>
<p>
<file>customtimer.pas</file> defines <var>TCustomTimer</var>, the component 
used as the ancestor for timer components in the Lazarus Component Library 
(<b>LCL</b>).
</p>
</descr>

<element name="Classes"/>
<element name="SysUtils"/>
<element name="LCLProc"/>
<element name="LCLStrConsts"/>
<element name="LCLType"/>
<element name="InterfaceBase"/>
<element name="CustApp"/>

<element name="TCustomTimer">
<short>
Defines the base class for <var>TTimer</var>.
</short>
<descr>
<p>
<var>TCustomTimer</var> is a <var>TComponent</var> descendant which specifies 
the base class for <var>TTimer</var>. TCustomTimer specifies the properties, 
methods, and events handlers used for timer classes in the LCL.
</p>
<p>
Use the <var>Enabled</var> property to indicate if the timer can be executed.
</p>
<p>
Use the <var>Interval</var> property to control the frequency of notification 
events from the executing timer class instance.
</p>
<p>
Use the <var>OnTimer</var>, <var>OnStartTimer</var>, and 
<var>OnStopTimer</var> event handlers to perform actions needed for the 
corresponding execution state in the timer class instance.
</p>
<p>
Do not create instances of TCustomTimer; use the <var>TTimer</var> descendant 
class in the <file>ExtCtrls.pp</file> unit.
</p>
</descr>
<seealso>
<link id="TCustomTimer.Enabled"/>
<link id="TCustomTimer.Interval"/>
<link id="TCustomTimer.OnTimer"/>
<link id="TCustomTimer.OnStartTimer"/>
<link id="TCustomTimer.OnStopTimer"/>
<link id="#lcl.extctrls.TTimer">TTimer</link>
</seealso>
</element>

<element name="TCustomTimer.FInterval"/>
<element name="TCustomTimer.FOnStartTimer"/>
<element name="TCustomTimer.FOnStopTimer"/>
<element name="TCustomTimer.FTimerHandle"/>
<element name="TCustomTimer.FOnTimer"/>
<element name="TCustomTimer.FEnabled"/>

<element name="TCustomTimer.Timer">
<short>
Procedure called when the timer interval has elapsed.
</short>
<descr>
<p>
<var>Timer</var> is a private procedure called when the <var>Interval</var> 
for the timer has elapsed. Timer calls the <var>DoOnTimer</var> method to 
perform a notification using the <var>OnTimer</var> event (when assigned). 
Assign a procedure to the <var>OnTimer</var> event handler to perform actions 
needed when the <var>Interval</var> for the timer has elapsed.
</p>
<p>
If an exception occurs in DoOnTimer, the <var>HandleException</var> method in 
the <var>CustomApplication</var> singleton is called.
</p>
<p>
The <var>Timer</var> procedure is passed as an argument when the timer handle 
is created for the widget set in its UpdateTimer method.
</p>
<remark>
Please note that the <var>OnTimer</var> event notification is not performed 
when <var>Enabled</var> contains <b>False</b> or when <var>Interval</var> 
contains the value <b>0</b> (<b>zero</b>).
</remark>
</descr>
<seealso>
<link id="TCustomTimer.OnTimer"/>
<link id="TCustomTimer.Enabled"/>
<link id="TCustomTimer.Interval"/>
<link id="TCustomTimer.UpdateTimer"/>
<link id="#fcl.custapp.TCustomApplication.HandleException">TCustomApplication.HandleException</link>
<link id="#fcl.custapp.CustomApplication">CustomApplication</link>
</seealso>
</element>
<element name="TCustomTimer.SetEnabled">
<short>Sets the value for the <var>Enabled</var> property.</short>
<seealso>
<link id="TCustomTimer.Enabled"/>
</seealso>
</element>
<element name="TCustomTimer.SetEnabled.Value">
<short>True when the timer can be executed.</short>
</element>
<element name="TCustomTimer.SetInterval">
<short>Sets the value for the <var>Interval</var> property.</short>
<seealso>
<link id="TCustomTimer.Interval"/>
</seealso>
</element>
<element name="TCustomTimer.SetInterval.Value">
<short>
The <var>Value</var> of the <var>Interval</var> property in milliseconds.
</short>
</element>
<element name="TCustomTimer.SetOnTimer">
<short>Sets the event handler for the <var>OnTimer</var> property.</short>
<seealso>
<link id="TCustomTimer.OnTimer"/>
</seealso>
</element>
<element name="TCustomTimer.SetOnTimer.Value">
<short>
<var>TNotifyEvent</var> handler signalled when the timer has expired.
</short>
</element>
<element name="TCustomTimer.DoOnTimer">
<short>
<var>DoOnTimer</var> signals the <var>OnTimer</var> event handler.
</short>
<descr>
<p>
<var>DoOnTimer</var> is a protected virtual procedure used to signal the 
<var>OnTimer</var> event handler (when assigned). No actions are performed in 
<var>DoOnTimer</var> when <var>OnTimer</var> has not been assigned (contains 
<b>Nil</b>).
</p>
<p>
<var>DoOnTimer</var> is called from the <var>Timer</var> method when 
<var>Enabled</var> contains <b>True</b> and <var>Interval</var> contains a 
value greater than <b>0</b> (<b>zero</b>).
</p>
<p>
Assign a procedure to <var>OnTimer</var> to perform the actions required when 
the <var>Interval</var> for the timer has elapsed.
</p>
<p>
Set the value in <var>Interval</var> to control the frequency of timer event 
notifications.
</p>
<p>
Set <var>Enabled</var> to <b>False</b> to prevent execution of the timer.
</p>
</descr>
<seealso>
<link id="TCustomTimer.OnTimer"/>
<link id="TCustomTimer.Enabled"/>
<link id="TCustomTimer.Interval"/>
</seealso>
</element>
<element name="TCustomTimer.UpdateTimer">
<short>Updates the Timer to reflect the current properties.</short>
<descr>
<p>
<var>UpdateTimer</var> is a protected virtual procedure used to update 
property values in the timer class instance. UpdateTimer calls 
<var>KillTimer</var> to stop the timer if it has been enabled and a widget 
set handle has been previously assigned for the class instance. The handle is 
recreated at run-time using the <var>Timer</var> method as a polling routine 
when <var>Enabled</var> contains <b>True</b>, <var>Interval</var> contains a 
value greater than <b>0</b> (<b>zero</b>), and <var>OnTimer</var> has been 
assigned for the class instance. The handle is not recreated if the component 
is being freed, or when the component is <var>Loaded</var> using the LCL 
streaming mechanism.
</p>
<p>
UpdateTimer can raise an <var>EOutOfResources</var> exception with the 
message in <var>SNoTimers</var> if a missing or invalid handle is returned 
from the widget set class.
</p>
<p>
UpdateTimer signals the <var>OnStartTimer</var> event handler when it has 
been assigned for the class instance. The event handler is not signalled when 
it has not been assigned (contains <b>Nil</b>), <var>Enabled</var> contains 
<b>False</b>, or <var>Interval</var> contains the value <b>0</b> 
(<b>zero</b>).
</p>
<p>
UpdateTimer is called from the <var>Loaded</var> method when component 
streaming has been completed, and when the value in the <var>OnTimer</var> 
event handler is changed.
</p>
</descr>
<errors>
<p>
Raises an <var>EOutOfResources</var> exception with the message in 
<var>SNoTimers</var> if a missing or invalid handle is returned from the 
widget set class.
</p>
</errors>
<seealso>
<link id="TCustomTimer.KillTimer"/>
<link id="TCustomTimer.Enabled"/>
<link id="TCustomTimer.Interval"/>
<link id="TCustomTimer.OnStartTimer"/>
<link id="TCustomTimer.OnTimer"/>
<link id="#rtl.classes.TComponent">TComponent</link>
</seealso>
</element>
<element name="TCustomTimer.KillTimer">
<short>Stops execution of the timer class instance.</short>
<descr>
<p>
<var>KillTimer</var> is a protected virtual procedure used to stop execution 
of the timer class instance. KillTimer ensures that a value widget set handle 
has been assigned for the timer class instance prior to freeing the handle 
and signalling the <var>OnStopTimer</var> event handler (when assigned). No 
actions are performed in the method if the widget set handle is not assigned 
or invalid.
</p>
<p>
KillTimer is called from the <var>UpdateTimer</var> method, and when the 
class instance is freed in the <var>Destroy</var> method.
</p>
</descr>
<seealso>
<link id="TCustomTimer.OnStopTimer"/>
<link id="TCustomTimer.UpdateTimer"/>
<link id="TCustomTimer.Destroy"/>
</seealso>
</element>

<element name="TCustomTimer.Loaded">
<short>
Performs actions needed when LCL component streaming has been completed.
</short>
<descr>
<p>
<var>Loaded</var> is an overridden method in <var>TCustomTimer</var>. It 
calls the inherited method on entry to remove <var>csLoading</var> from the 
<var>ComponentState</var> property.
</p>
<p>
Loaded calls <var>UpdateTimer</var> to re-create the timer handle and signal 
event event handlers as needed for the Enabled property in the timer. An 
<var>EOutOfResources</var> exception is raised (in UpdateTimer) if a timer 
handle cannot be allocated in the widgetset class.
</p>
</descr>
<seealso>
<link id="TCustomTimer.UpdateTimer"/>
<link id="#rtl.classes.TComponent.ComponentState">TComponent.ComponentState</link>
</seealso>
</element>

<element name="TCustomTimer.Create">
<short>
<var>Create</var> - constructor for <var>TCustomTimer</var>: calls inherited 
<var>Create</var>, sets up handle and initializes timer interval.
</short>
<descr>
<p>
<var>Create</var> is the overridden constructor for the class instance. 
Create calls the inherited constructor using the component in 
<var>AOwner</var> as the owner for the class instance.
</p>
<p>
Create sets the default values for properties in the timer class instance; 
the timer Interval is set to <b>1000ms</b> (<b>1 second</b>) and the 
<var>Enabled</var> property is set to <b>True</b>. The internal handle for 
the timer instance is set to the value which represents an invalid or 
unassigned handle (<b>-1</b>).
</p>
<p>
Change the value in the <var>Interval</var> property to alter the frequency 
of the timer notification.
</p>
<p>
Assigned an object procedure to the <var>OnTimer</var> event handler to 
perform actions needed when the timer Interval has expired.
</p>
</descr>
<errors/>
<seealso>
<link id="TCustomTimer.Interval"/>
<link id="TCustomTimer.Enabled"/>
<link id="TCustomTimer.OnTimer"/>
<link id="#rtl.classes.TComponent.Create">TComponent.Create</link>
</seealso>
</element>
<element name="TCustomTimer.Create.AOwner">
<short>Component which owns the timer class instance.</short>
</element>
<element name="TCustomTimer.Destroy">
<short>Destructor for the timer class instance.</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the class instance. 
Destroy ensures that the <var>OnTimer</var> event handler is unassigned and 
<var>Enabled</var> is set to <b>False</b> before halting the timer by calling 
the <var>KillTimer</var> method.
</p>
<p>
Destroy calls the inherited destructor prior to exiting from the method.
</p>
<p>
Use the OnStopTimer event handler to perform actions needed when the timer is 
disabled or freed.
</p>
</descr>
<errors/>
<seealso>
<link id="TCustomTimer.Enabled"/>
<link id="TCustomTimer.OnTimer"/>
<link id="TCustomTimer.KillTimer"/>
<link id="TCustomTimer.OnStopTimer"/>
<link id="#rtl.classes.TComponent.Destroy">TComponent.Destroy</link>
</seealso>
</element>
<element name="TCustomTimer.Enabled">
<short>Indicates if the timer is ready to start.</short>
<descr>
<p>
<var>Enabled</var> is a <var>Boolean</var> property which controls the state 
for the timer class instance. When Enabled contains True the timer can be 
executed, and its <var>OnTimer</var> event handler is signalled when the 
Interval for the timer has elapsed. Changing the value in Enabled causes the 
<var>UpdateTimer</var> method to be called to set the current value for 
properties in the timer.
</p>
</descr>
<seealso>
<link id="TCustomTimer.Create"/>
<link id="TCustomTimer.Destroy"/>
<link id="TCustomTimer.Interval"/>
<link id="TCustomTimer.UpdateTimer"/>
<link id="TCustomTimer.OnStartTimer"/>
<link id="TCustomTimer.OnStopTimer"/>
<link id="TCustomTimer.OnTimer"/>
</seealso>
</element>
<element name="TCustomTimer.Interval">
<short>
The <var>Interval</var> (in milliseconds) for timer notifications.
</short>
<descr>
<p>
<var>Interval</var> is a <var>Cardinal</var> property which indicates the 
frequency (in milliseconds) for OnTimer event notifications during timer 
execution. The default value for the property is <b>1000</b> milliseconds (or 
<b>1</b> second).
</p>
<p>
Changing the value in Interval causes the <var>UpdateTimer</var> method to be 
called to update the values for properties in the timer class instance. 
Setting the value in Interval to <b>0</b> (<b>zero</b>) prevents the timer 
from allocating it handle and performing the OnStartTimer event handler when 
Enabled is changed to <b>True</b>.
</p>
<p>
Use <var>Enabled</var> to indicate if the timer can be executed.
</p>
<p>
Use the <var>OnStartTimer</var>, <var>OnStopTimer</var>, and 
<var>OnTimer</var> event handlers to perform actions needed for the 
corresponding execution states in the timer class instance.
</p>
</descr>
<seealso>
<link id="TCustomTimer.Enabled"/>
<link id="TCustomTimer.UpdateTimer"/>
<link id="TCustomTimer.OnStartTimer"/>
<link id="TCustomTimer.OnStopTimer"/>
<link id="TCustomTimer.OnTimer"/>
</seealso>
</element>
<element name="TCustomTimer.OnTimer">
<short>
Event handler signalled when the Interval for the timer has elapsed.
</short>
<descr>
<p>
<var>OnTimer</var> is a <var>TNotifyEvent</var> property that implements the 
event handler signalled when the <var>Interval</var> for the timer has 
elapsed. The default value for the property is <b>Nil</b> as assigned in the 
constructor for the class instance.
</p>
<p>
Assign a <var>TNotifyEvent</var> procedure to the event handler to perform 
actions needed for the event notification. Setting the value in OnTimer 
causes the UpdateTimer method to be called to reflect the current values for 
the timer class instance.
</p>
<remark>
Please note that <var>OnTimer</var> is not signalled during timer execution 
when <var>Interval</var> contains the value <b>0</b> (<b>zero</b>).
</remark>
<p>
Use the <var>OnStartTimer</var> event handler to perform actions required 
when the timer is started by setting <var>Enabled</var> to <b>True</b>.
</p>
<p>
Use the <var>OnStopTimer</var> event handler to perform actions needed when 
the timer is halted by setting <var>Enabled</var> to <b>False</b>, or when 
calling the destructor for an executing timer class instance.
</p>
</descr>
<seealso>
<link id="TCustomTimer.Interval"/>
<link id="TCustomTimer.Enabled"/>
<link id="TCustomTimer.OnStartTimer"/>
<link id="TCustomTimer.OnStopTimer"/>
<link id="TCustomTimer.UpdateTimer"/>
</seealso>
</element>
<element name="TCustomTimer.OnStartTimer">
<short>Event handler signalled when the timer is started.</short>
<descr>
<p>
<var>OnStartTimer</var> is a <var>TNotifyEvent</var> property that implements 
the event handler signalled when the timer class instance is started. Assign 
a TNotifyEvent procedure to the event handler to perform actions needed 
to reflect the change in the timer state. No actions are performed for the 
event notification when OnStartTimer is unassigned (contains <b>Nil</b>).
</p>
<p>
OnStartTimer is signalled from the <var>UpdateTimer</var> method when the 
value in the <var>Enabled</var> property is changed to <b>True</b>.
</p>
<remark>
Please note that <var>OnStartTimer</var> is not signalled when 
<var>Interval</var> contains the value <b>0</b> (<b>zero</b>).
</remark>
<p>
Use the <var>OnStopTimer</var> event handler to perform actions needed when 
the timer class instance is stopped (or freed during execution).
</p>
<p>
Use the <var>OnTimer</var> event handler to perform actions needed when the 
<var>Interval</var> for the timer has elapsed.
</p>
</descr>
<seealso>
<link id="TCustomTimer.Interval"/>
<link id="TCustomTimer.Enabled"/>
<link id="TCustomTimer.OnStopTimer"/>
<link id="TCustomTimer.OnTimer"/>
</seealso>
</element>
<element name="TCustomTimer.OnStopTimer">
<short>
<var>OnStopTimer</var> - event handler for stopping the timer.
</short>
<descr>
<p>
<var>OnStopTimer</var> is a <var>TNotifyEvent</var> property that implements 
the event handler signalled when the timer class instance is stopped. Assign 
a <var>TNotifyEvent</var> procedure to the property to perform actions needed 
when the timer is halted (or freed during execution). No actions are 
performed for the event notification when <var>OnStopTimer</var> is 
unassigned (contains <b>Nil</b>).
</p>
<p>
<var>OnStopTimer</var> is signalled from the <var>KillTimer</var> method when 
the timer class instance has been started and the property has been assigned.
</p>
<p>
Use the <var>OnStartTimer</var> event handler to perform actions needed when 
the timer class instance is started.
</p>
<p>
Use the <var>OnTimer</var> event handler to perform actions needed when the 
<var>Interval</var> for the timer has elapsed.
</p>
</descr>
<seealso>
<link id="TCustomTimer.Interval"/>
<link id="TCustomTimer.Enabled"/>
<link id="TCustomTimer.OnStartTimer"/>
<link id="TCustomTimer.OnTimer"/>
</seealso>
</element>
</module>
<!-- CustomTimer -->
</package>
</fpdoc-descriptions>