mirror of
https://gitlab.com/freepascal.org/lazarus/lazarus.git
synced 2025-04-26 18:43:50 +02:00
379 lines
20 KiB
XML
379 lines
20 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<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 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>
|