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
|
<?xml version="1.0" encoding="UTF-8"?>
<helpdocument version="1.0">
<!--
* This file is part of the LibreOffice project.
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
*
-->
<meta>
<topic id="SF_Timer" indexer="include" status="PUBLISH">
<title id="tit" xml-lang="en-US">ScriptForge.Timer service</title>
<filename>/text/sbasic/shared/03/sf_timer.xhp</filename>
</topic>
</meta>
<body>
<section id="ScriptForge-sf_timer">
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id261582733781987">
<bookmark_value>Timer service</bookmark_value>
</bookmark>
</section>
<section id="abstract">
<h1 id="hd_id731582733781114" xml-lang="en-US"><variable id="TimerService"><link href="text/sbasic/shared/03/sf_timer.xhp"><literal>ScriptForge</literal>.<literal>Timer</literal> service</link></variable></h1>
<paragraph role="paragraph" id="par_id961582733781662" xml-lang="en-US">The <literal>Timer</literal> service measures the amount of time it takes to run user scripts.</paragraph>
<paragraph role="paragraph" id="par_id181582733781323" xml-lang="en-US">A <literal>Timer</literal> measures <emph>durations</emph>. It can be:</paragraph>
<list type="unordered">
<listitem>
<paragraph id="par_id711582733781252" role="listitem" xml-lang="en-US">Started, to indicate when to start measuring time.</paragraph>
</listitem>
<listitem>
<paragraph id="par_id631582733781431" role="listitem" xml-lang="en-US">Suspended, to pause measuring running time.</paragraph>
</listitem>
<listitem>
<paragraph id="par_id691582733781498" role="listitem" xml-lang="en-US">Resumed, to continue tracking running time after the Timer has been suspended.</paragraph>
</listitem>
<listitem>
<paragraph id="par_id31582733781344" role="listitem" xml-lang="en-US">Restarted, which will cancel previous measurements and start the <literal>Timer</literal> at zero.</paragraph>
</listitem>
</list>
</section>
<paragraph role="tip" id="par_id991582733781280" xml-lang="en-US">Durations are expressed in seconds with a precision of 3 decimal digits (milliseconds). A duration value of 12.345 means 12 seconds and 345 milliseconds</paragraph>
<h2 id="hd_id201582733781265" xml-lang="en-US">Service invocation</h2>
<paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>Timer</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph>
<embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<paragraph role="paragraph" id="par_id891610734806133">The example below creates a <literal>Timer</literal> object named <literal>myTimer</literal> and starts it immediately.</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id551610734764343">GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")</paragraph>
<paragraph role="bascode" localize="false" id="bas_id11582733781672">Dim myTimer As Variant</paragraph>
<paragraph role="bascode" localize="false" id="bas_id31582733781292">myTimer = CreateScriptService("Timer", True)</paragraph>
<paragraph role="bascode" id="bas_id681582733781715">'The timer starts immediately when the second argument = True, default = False</paragraph>
</bascode>
<paragraph role="paragraph" id="par_id891582733781994" xml-lang="en-US">It is recommended to free resources after use:</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id61582733781413">Set myTimer = myTimer.Dispose()</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id351626871397672">from scriptforge import CreateScriptService</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id851626871397921">myTimer = CreateScriptService("Timer", start = True)</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id301626871398065"># ...</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id661626871405884">myTimer = myTimer.Dispose()</paragraph>
</pycode>
<h2 id="hd_id521582733781450" xml-lang="en-US">Properties</h2>
<section id="properties_toc">
<table id="tab_id761582733781447">
<tablerow>
<tablecell>
<paragraph id="par_id71582733781260" role="tablehead" xml-lang="en-US">Name</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id711582733781103" role="tablehead" xml-lang="en-US">Readonly</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id76158273378122" role="tablehead" xml-lang="en-US">Type</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id751582733781926" role="tablehead" xml-lang="en-US" >Description</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id561582733781781" role="tablecontent" xml-lang="en-US" localize="false">Duration</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id621582733781588" role="tablecontent" xml-lang="en-US">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id521582733781943" role="tablecontent" xml-lang="en-US" localize="false">Double</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id731582733781476" role="tablecontents" xml-lang="en-US" >The actual running time elapsed since start or between start and stop (does not consider suspended time)</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id181582733781163" role="tablecontent" xml-lang="en-US" localize="false">IsStarted</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id301582733781498" role="tablecontent" xml-lang="en-US">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id591582733781696" role="tablecontent" xml-lang="en-US" localize="false">Boolean</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id401582733781608" role="tablecontents" xml-lang="en-US" ><literal>True</literal> when timer is started or suspended</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id371582733781716" role="tablecontent" xml-lang="en-US" localize="false">IsSuspended</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id181582733781551" role="tablecontent" xml-lang="en-US">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id411582733781116" role="tablecontent" xml-lang="en-US" localize="false">Boolean</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id161582733781328" role="tablecontents" xml-lang="en-US" ><literal>True</literal> when timer is started and suspended</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id691582733781260" role="tablecontent" xml-lang="en-US" localize="false">SuspendDuration</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id651582733781874" role="tablecontent" xml-lang="en-US">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id581582733781213" role="tablecontent" xml-lang="en-US" localize="false">Double</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id171582733781456" role="tablecontents" xml-lang="en-US" >The actual time elapsed while suspended since start or between start and stop</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id411582733781943" role="tablecontent" xml-lang="en-US" localize="false">TotalDuration</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id141582733781303" role="tablecontent" xml-lang="en-US">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id451582733781978" role="tablecontent" xml-lang="en-US" localize="false">Double</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id411582733781932" role="tablecontents" xml-lang="en-US" >The actual time elapsed since start or between start and stop (including suspensions and running time)</paragraph>
</tablecell>
</tablerow>
</table>
</section>
<paragraph role="tip" id="par_id9158273378151">Note that the <literal>TotalDuration</literal> property is equivalent to summing the <literal>Duration</literal> and <literal>SuspendDuration</literal> properties.</paragraph>
<h2 id="hd_id141582734141895" xml-lang="en-US">Methods</h2>
<paragraph role="paragraph" id="par_id291582734377752" xml-lang="en-US">All methods do not require arguments and return a <literal>Boolean</literal> value.</paragraph>
<paragraph role="paragraph" id="par_id311582734894257" xml-lang="en-US">If the returned value is <literal>False</literal>, then nothing happened.</paragraph>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id911610740799006">
<bookmark_value>Timer service;Continue</bookmark_value>
<bookmark_value>Timer service;Restart</bookmark_value>
<bookmark_value>Timer service;Start</bookmark_value>
<bookmark_value>Timer service;Suspend</bookmark_value>
<bookmark_value>Timer service;Terminate</bookmark_value>
</bookmark>
<section id="methods_toc">
<table id="tab_id231582734180676">
<tablerow>
<tablecell>
<paragraph id="par_id871582734180676" role="tablehead" xml-lang="en-US">Name</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id971582734180676" role="tablehead" xml-lang="en-US">Description</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id911582734180676" role="tablehead" xml-lang="en-US">Returned value</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id31582734180676" localize="False" role="tablecontent" xml-lang="en-US">Continue</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id301582734180676" role="tablecontent" xml-lang="en-US">Resumes the <literal>Timer</literal> if it has been suspended</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id661582734180676" role="tablecontent" xml-lang="en-US"><literal>False</literal> if the timer is not suspended</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id881582734649304" localize="False" role="tablecontent" xml-lang="en-US">Restart</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id821582734649305" role="tablecontent" xml-lang="en-US">Terminates the <literal>Timer</literal> and discards its current property values, restarting as a new clean <literal>Timer</literal></paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id761582734649305" role="tablecontent" xml-lang="en-US"><literal>False</literal> if the timer is inactive</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id201582734802443" localize="False" role="tablecontent" xml-lang="en-US">Start</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id641582734802443" role="tablecontent" xml-lang="en-US">Starts a new clean timer</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id921582734802443" role="tablecontent" xml-lang="en-US"><literal>False</literal> if the timer is already started</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id781582734905507" localize="False" role="tablecontent" xml-lang="en-US">Suspend</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id81582734905507" role="tablecontent" xml-lang="en-US">Suspends a running timer</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id661582734905507" role="tablecontent" xml-lang="en-US"><literal>False</literal> if the timer is not started or already suspended</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id771582734996722" localize="False" role="tablecontent" xml-lang="en-US">Terminate</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id861582734996722" role="tablecontent" xml-lang="en-US">Stops a running timer</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id381582734996722" role="tablecontent" xml-lang="en-US"><literal>False</literal> if the timer is neither started nor suspended</paragraph>
</tablecell>
</tablerow>
</table>
</section>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<paragraph role="paragraph" id="par_id731626871820490">The examples below in Basic and Python illustrate the use of the methods and properties in the <literal>Timer</literal> service.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id711582735902164">myTimer.Start()</paragraph>
<paragraph role="bascode" localize="false" id="bas_id371582735909094">Wait 500</paragraph>
<paragraph role="bascode" localize="false" id="bas_id691582735916493">myTimer.Suspend()</paragraph>
<paragraph role="bascode" id="bas_id141582735926821">'The time elapsed while the Dialog box is open will be counted as suspended time</paragraph>
<paragraph role="bascode" localize="false" id="bas_id1001582735936992">MsgBox myTimer.Duration & " " & myTimer.SuspendDuration & " " & myTimer.TotalDuration</paragraph>
<paragraph role="bascode" localize="false" id="bas_id361582735943749">myTimer.Continue()</paragraph>
<paragraph role="bascode" localize="false" id="bas_id71582735950518">Wait 500</paragraph>
<paragraph role="bascode" id="bas_id901582735961725">'The time elapsed while the Dialog box is open will be counted as running time</paragraph>
<paragraph role="bascode" localize="false" id="bas_id621610739916646">MsgBox myTimer.Duration & " " & myTimer.SuspendDuration & " " & myTimer.TotalDuration</paragraph>
<paragraph role="bascode" localize="false" id="bas_id51610739919950">myTimer.Terminate()</paragraph>
<paragraph role="bascode" id="bas_id941610739926687">'Shows the final time measurements</paragraph>
<paragraph role="bascode" localize="false" id="bas_id291610739929200">MsgBox myTimer.Duration & " " & myTimer.SuspendDuration & " " & myTimer.TotalDuration</paragraph>
</bascode>
<note id="par_id281610740093006">If you call the <literal>Terminate</literal> method, subsequent calls for the <literal>Continue</literal> method will not resume time measurement. Similarly, after a Timer has been terminated, calling the <literal>Start</literal> method will restart it as if it were a clean new Timer.</note>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id731626871933079">from time import sleep</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id921626871933367">bas = CreateScriptService("Basic")</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id101626871933551">myTimer.Start()</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id961626871933734">sleep(0.5)</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id351626871933894">myTimer.Suspend()</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id761626871934072">bas.MsgBox("{} {} {}".format(myTimer.Duration, myTimer.SuspendDuration, myTimer.TotalDuration))</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id411626871934239">myTimer.Continue()</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id941626871934407">sleep(0.5)</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id521626871934590">bas.MsgBox("{} {} {}".format(myTimer.Duration, myTimer.SuspendDuration, myTimer.TotalDuration))</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id921626871934776">myTimer.Terminate()</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id531626872457511">bas.MsgBox("{} {} {}".format(myTimer.Duration, myTimer.SuspendDuration, myTimer.TotalDuration))</paragraph>
</pycode>
<note id="par_id391626872019832">Be aware that the <literal>Wait</literal> function in BASIC takes in a duration argument in milliseconds whereas the <literal>sleep</literal> function in Python uses seconds in its argument.</note>
<h2 id="hd_id431610989623086">Working with Multiple Timers</h2>
<paragraph role="paragraph" id="par_id741610989639201">It is possible to instantiate multiple <literal>Timer</literal> services in parallel, which gives flexibility in measuring time in different parts of the code.</paragraph>
<paragraph role="paragraph" id="par_id921610989722908">The following example illustrates how to create two <literal>Timer</literal> objects and start them separately.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id771610989793244">Dim myTimerA as Variant, myTimerB as Variant</paragraph>
<paragraph role="bascode" localize="false" id="bas_id261610989825466">myTimerA = CreateScriptService("Timer")</paragraph>
<paragraph role="bascode" localize="false" id="bas_id931610989829730">myTimerB = CreateScriptService("Timer")</paragraph>
<paragraph role="bascode" id="bas_id481610989853679">'Starts myTimerA</paragraph>
<paragraph role="bascode" localize="false" id="bas_id911610989839892">myTimerA.Start()</paragraph>
<paragraph role="bascode" localize="false" id="bas_id871610989842236">Wait 1000 'Wait 1 second (1,000 milliseconds)</paragraph>
<paragraph role="bascode" localize="false" id="bas_id571610989855742">MsgBox myTimerA.Duration & " " & myTimerB.Duration</paragraph>
<paragraph role="bascode" id="bas_id331610989849501">'Starts myTimerB</paragraph>
<paragraph role="bascode" localize="false" id="bas_id341610989847112">myTimerB.Start()</paragraph>
<paragraph role="bascode" localize="false" id="bas_id571610989851550">Wait 1000</paragraph>
<paragraph role="bascode" localize="false" id="bas_id51610989832354">MsgBox myTimerA.Duration & " " & myTimerB.Duration</paragraph>
<paragraph role="bascode" id="bas_id931610989837747">'Terminate both timers</paragraph>
<paragraph role="bascode" localize="false" id="bas_id631610989844852">myTimerA.Terminate()</paragraph>
<paragraph role="bascode" localize="false" id="bas_id411610989835115">myTimerB.Terminate()</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id711626872551380">from time import sleep</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id541626872551709">myTimerA = CreateScriptService("Timer")</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id581626872551876">myTimerB = CreateScriptService("Timer")</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id441626872552076">myTimerA.Start()</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id631626872552268">sleep(1)</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id41626872552468">bas.MsgBox("{} {}".format(myTimerA.Duration, myTimerB.Duration))</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id891626872552670">myTimerB.Start()</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id321626872552868">sleep(1)</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id11626872553077">bas.MsgBox("{} {}".format(myTimerA.Duration, myTimerB.Duration))</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id441626872553324">myTimerA.Terminate()</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id161626872553821">myTimerB.Terminate()</paragraph>
</pycode>
<embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/>
<section id="relatedtopics">
<embed href="text/sbasic/shared/03030203.xhp#Now_H1"/>
<embed href="text/sbasic/shared/03030303.xhp#Timer_H1"/>
</section>
</body>
</helpdocument>
|
