1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
|
<?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>
|
