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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html>
<head>
<title>Castle Game Engine: CastleProgress: Class TProgress</title>
<meta name="generator" content="PasDoc 0.13.0">
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<link rel="StyleSheet" type="text/css" href="pasdoc.css">
</head>
<body>
<table class="container"><tr><td class="navigation">
<h2>Castle Game Engine</h2><p><a href="introduction.html" class="navigation">Introduction</a></p><p><a href="AllUnits.html" class="navigation">Units</a></p><p><a href="ClassHierarchy.html" class="navigation">Class Hierarchy</a></p><p><a href="AllClasses.html" class="navigation">Classes, Interfaces, Objects and Records</a></p><p><a href="AllTypes.html" class="navigation">Types</a></p><p><a href="AllVariables.html" class="navigation">Variables</a></p><p><a href="AllConstants.html" class="navigation">Constants</a></p><p><a href="AllFunctions.html" class="navigation">Functions and Procedures</a></p><p><a href="AllIdentifiers.html" class="navigation">Identifiers</a></p></td><td class="content">
<a name="TProgress"></a><h1 class="cio">Class TProgress</h1>
<table class="sections wide_list">
<tr>
<td><a class="section" href="#PasDoc-Description">Description</a></td><td><a class="section" href="#PasDoc-Hierarchy">Hierarchy</a></td><td><a class="section" href="#PasDoc-Fields">Fields</a></td><td><a class="section" href="#PasDoc-Methods">Methods</a></td><td><a class="section" href="#PasDoc-Properties">Properties</a></td></tr></table>
<a name="PasDoc-Description"></a><h2 class="unit">Unit</h2>
<p class="unitlink">
<a href="CastleProgress.html">CastleProgress</a></p>
<h2 class="declaration">Declaration</h2>
<p class="declaration">
<code>type TProgress = class(TObject)</code></p>
<h2 class="description">Description</h2>
<p>
Progress bar functionality.
<p>This provides the functionality of a progress bar (everything that wants to signal progress should call <a class="normal" href="CastleProgress.html#Progress">Progress</a> methods), but not the actual user interface. The user interface is "pluggable", that is you assign something to the Progress.UserInterface property. See the units:
<p></p>
<ul class="compact_spacing">
<li><p><a class="normal" href="CastleWindowProgress.html">CastleWindowProgress</a> — show progress bar in OpenGL window</p></li>
<li><p><a class="normal" href="CastleProgressConsole.html">CastleProgressConsole</a> — show progress bar on StdErr</p></li>
<li><p>And you can also implement progress handling yourself, e.g. using Lazarus form or using Lazarus progress bar on existing form.</p></li>
</ul>
<p>
<p>This way any unit that implements some lengthy operation can call appropriate functions of the <a class="normal" href="CastleProgress.html#Progress">Progress</a> object. And the final program can choose how it wants to show that progress to user (in console? in OpenGL window? etc.).
<p>Usage example:
<p></p>
<pre class="longcode">
Progress.UserInterface := <span class="pascal_numeric"></span>... some TProgressUserInterface instance <span class="pascal_numeric"></span>...;
<span class="pascal_numeric"></span>...
Progress.Init(<span class="pascal_numeric">100</span>, <span class="pascal_string">'Doing something time-consuming, please wait'</span>);
<span class="pascal_keyword">try</span>
<span class="pascal_keyword">for</span> i := <span class="pascal_numeric">1</span> <span class="pascal_keyword">to</span> <span class="pascal_numeric">100</span> <span class="pascal_keyword">do</span>
<span class="pascal_keyword">begin</span>
<span class="pascal_numeric"></span>... <span class="pascal_keyword">do</span> something <span class="pascal_numeric"></span>...
Progress.Step;
<span class="pascal_keyword">end</span>;
<span class="pascal_keyword">finally</span> Progress.Fini; <span class="pascal_keyword">end</span>;
</pre>
<p>
<p>Using <code>"try ... finally ... end"</code> above is not strictly required, but is strongly suggested. Rule of thumb says to always call Progress.Fini when you called Progress.Init.
<p>The <a class="normal" href="CastleProgress.TProgress.html#Step">TProgress.Step</a> is implemented such that you don't have to worry about calling it too often. We will not update the interface (<a class="normal" href="CastleProgress.TProgressUserInterface.html#Update">TProgressUserInterface.Update</a>) too often, see <a class="normal" href="CastleProgress.TProgress.html#UpdatePart">TProgress.UpdatePart</a> and <a class="normal" href="CastleProgress.TProgress.html#UpdateTicks">TProgress.UpdateTicks</a> for details.
<p>This unit creates one instance of the class <a class="normal" href="CastleProgress.TProgress.html">TProgress</a>: <a class="normal" href="CastleProgress.html#Progress">Progress</a>. Usually this is what you want to use. For complicated cases, you can create and pass around more instances (e.g. from different threads, each <a class="normal" href="CastleProgress.TProgress.html">TProgress</a> object displaying it's state in a separate window.)</p>
<a name="PasDoc-Hierarchy"></a><h2 class="hierarchy">Hierarchy</h2>
<ul class="hierarchy"><li class="ancestor">TObject</li>
<li class="thisitem">TProgress</li></ul><h2 class="overview">Overview</h2>
<a name="PasDoc-Fields"></a><h3 class="summary">Fields</h3>
<table class="summary wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>internal const <b><a href="CastleProgress.TProgress.html#DefaultUpdatePart">DefaultUpdatePart</a></b> = 100 ;</code></td>
</tr>
<tr class="list2">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>internal const <b><a href="CastleProgress.TProgress.html#DefaultUpdateTicks">DefaultUpdateTicks</a></b> = 250 ;</code></td>
</tr>
</table>
<a name="PasDoc-Methods"></a><h3 class="summary">Methods</h3>
<table class="summary wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>procedure <b><a href="CastleProgress.TProgress.html#Init">Init</a></b>(AMax: Cardinal; const ATitle: string; const DelayUserInterface: boolean = false);</code></td>
</tr>
<tr class="list2">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>procedure <b><a href="CastleProgress.TProgress.html#Step">Step</a></b>(StepSize: Cardinal = 1);</code></td>
</tr>
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>procedure <b><a href="CastleProgress.TProgress.html#Fini">Fini</a></b>;</code></td>
</tr>
<tr class="list2">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>constructor <b><a href="CastleProgress.TProgress.html#Create">Create</a></b>;</code></td>
</tr>
</table>
<a name="PasDoc-Properties"></a><h3 class="summary">Properties</h3>
<table class="summary wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>property <b><a href="CastleProgress.TProgress.html#UserInterface">UserInterface</a></b>: <a href="CastleProgress.TProgressUserInterface.html">TProgressUserInterface</a>
read FUserInterface write FUserInterface;</code></td>
</tr>
<tr class="list2">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>property <b><a href="CastleProgress.TProgress.html#UpdatePart">UpdatePart</a></b>: Cardinal read FUpdatePart write FUpdatePart
default <a href="CastleProgress.TProgress.html#DefaultUpdatePart">DefaultUpdatePart</a>;</code></td>
</tr>
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>property <b><a href="CastleProgress.TProgress.html#UpdateTicks">UpdateTicks</a></b>: <a href="CastleTimeUtils.html#TMilisecTime">TMilisecTime</a> read FUpdateTicks write FUpdateTicks
default <a href="CastleProgress.TProgress.html#DefaultUpdateTicks">DefaultUpdateTicks</a>;</code></td>
</tr>
<tr class="list2">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>property <b><a href="CastleProgress.TProgress.html#Position">Position</a></b>: Cardinal read FPosition write SetPosition;</code></td>
</tr>
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>property <b><a href="CastleProgress.TProgress.html#Max">Max</a></b>: Cardinal read FMax;</code></td>
</tr>
<tr class="list2">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>property <b><a href="CastleProgress.TProgress.html#Title">Title</a></b>: string read FTitle;</code></td>
</tr>
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>property <b><a href="CastleProgress.TProgress.html#Active">Active</a></b>: boolean read FActive;</code></td>
</tr>
</table>
<h2 class="description">Description</h2>
<h3 class="detail">Fields</h3>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="DefaultUpdatePart"></a><code>internal const <b>DefaultUpdatePart</b> = 100 ;</code></td>
</tr>
<tr><td colspan="2">
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="DefaultUpdateTicks"></a><code>internal const <b>DefaultUpdateTicks</b> = 250 ;</code></td>
</tr>
<tr><td colspan="2">
</td></tr>
</table>
<h3 class="detail">Methods</h3>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="Init"></a><code>procedure <b>Init</b>(AMax: Cardinal; const ATitle: string; const DelayUserInterface: boolean = false);</code></td>
</tr>
<tr><td colspan="2">
<p>
Start the progress bar. You can call Init only when Active = false (that is, you cannot Init while another progress is working). Initializes <a class="normal" href="CastleProgress.TProgress.html#Max">Max</a>, <a class="normal" href="CastleProgress.TProgress.html#Title">Title</a>, sets <a class="normal" href="CastleProgress.TProgress.html#Position">Position</a> to 0 and changes <a class="normal" href="CastleProgress.TProgress.html#Active">Active</a> to true.
<p><a class="normal" href="CastleProgress.TProgress.html#UserInterface">UserInterface</a> must be initialized (non-nil) when calling Init, and you cannot change <a class="normal" href="CastleProgress.TProgress.html#UserInterface">UserInterface</a> when progress is Active (i.e. before you call Fini).
<p>If DelayUserInterface is set to <code>True</code>, a very useful optimization is performed: <code>TProgress.Init</code> will not immediately result in <a class="normal" href="CastleProgress.TProgressUserInterface.html#Init">TProgressUserInterface.Init</a> call. Instead, actual initialization of the interface will be delayed until some TProgress.Update, when <a class="normal" href="CastleProgress.TProgress.html#UpdateTicks">UpdateTicks</a> time will pass.
<p>The advantage of DelayUserInterface is that if an operation will take a very short time, we will not waste time on possibly lengthy initialization of the progress bar interface. For example, <a class="normal" href="CastleWindowProgress.html">CastleWindowProgress</a> may have to capture OpenGL screen at the initialization, which takes a noticeable fraction of second by itself. So it's not sensible to init <a class="normal" href="CastleWindowProgress.html">CastleWindowProgress</a> if an entire operation between Progress.Init and Fini will take only 0.001 of second..
<p>The only downside of DelayUserInterface is that it's not applicable to an operation with very few steps (e.g. 1) that may take a long time. If a time between Init and the first Update or Fini is really large, the progress bar will not be visible.</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="Step"></a><code>procedure <b>Step</b>(StepSize: Cardinal = 1);</code></td>
</tr>
<tr><td colspan="2">
<p>
Increments progress bar <a class="normal" href="CastleProgress.TProgress.html#Position">Position</a> by <code>StepSize</code>. Use only when <a class="normal" href="CastleProgress.TProgress.html#Active">Active</a>, that is between <a class="normal" href="CastleProgress.TProgress.html#Init">Init</a> and <a class="normal" href="CastleProgress.TProgress.html#Fini">Fini</a> calls.
<p><a class="normal" href="CastleProgress.TProgress.html#Position">Position</a> always stays <= <a class="normal" href="CastleProgress.TProgress.html#Max">Max</a> (you can depend on this when implementaing <a class="normal" href="CastleProgress.TProgressUserInterface.html">TProgressUserInterface</a> descendants). But it is legal to try to raise <a class="normal" href="CastleProgress.TProgress.html#Position">Position</a> above <a class="normal" href="CastleProgress.TProgress.html#Max">Max</a> by using this method, we will silently clamp <a class="normal" href="CastleProgress.TProgress.html#Position">Position</a> to <a class="normal" href="CastleProgress.TProgress.html#Max">Max</a>. This is usefull when given <a class="normal" href="CastleProgress.TProgress.html#Max">Max</a> was only an approximation of needed steps.</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="Fini"></a><code>procedure <b>Fini</b>;</code></td>
</tr>
<tr><td colspan="2">
<p>
Finish progress bar. You can call it only when Active = true (that is, if you called Init before). Fini changes Active to false.
<p>Note that it's perfectly legal to call Fini before Position reaches Max (it's sensible e.g. when you're allowing user to break some lenghty operation, or when Max was only an approximation of steps needed).</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="Create"></a><code>constructor <b>Create</b>;</code></td>
</tr>
<tr><td colspan="2">
</td></tr>
</table>
<h3 class="detail">Properties</h3>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="UserInterface"></a><code>property <b>UserInterface</b>: <a href="CastleProgress.TProgressUserInterface.html">TProgressUserInterface</a>
read FUserInterface write FUserInterface;</code></td>
</tr>
<tr><td colspan="2">
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="UpdatePart"></a><code>property <b>UpdatePart</b>: Cardinal read FUpdatePart write FUpdatePart
default <a href="CastleProgress.TProgress.html#DefaultUpdatePart">DefaultUpdatePart</a>;</code></td>
</tr>
<tr><td colspan="2">
<p>
Define how often to redraw interface (<a class="normal" href="CastleProgress.TProgressUserInterface.html#Update">TProgressUserInterface.Update</a>). Position must change by (1/<code>UpdatePart</code>) * Max and at the same time at least <a class="normal" href="CastleProgress.TProgress.html#UpdateTicks">UpdateTicks</a> miliseconds must pass to redraw.
<p>This allows you to call <a class="normal" href="CastleProgress.TProgress.html#Step">Step</a> very often, without worrying that you cause redraw too often (which would cause slowdown). </p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="UpdateTicks"></a><code>property <b>UpdateTicks</b>: <a href="CastleTimeUtils.html#TMilisecTime">TMilisecTime</a> read FUpdateTicks write FUpdateTicks
default <a href="CastleProgress.TProgress.html#DefaultUpdateTicks">DefaultUpdateTicks</a>;</code></td>
</tr>
<tr><td colspan="2">
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="Position"></a><code>property <b>Position</b>: Cardinal read FPosition write SetPosition;</code></td>
</tr>
<tr><td colspan="2">
<p>
Current Position of the progress bar. Always >= 0 and <= <a class="normal" href="CastleProgress.TProgress.html#Max">Max</a>.
<p>You can set this property only when <a class="normal" href="CastleProgress.TProgress.html#Active">Active</a>. Setting it to something > <a class="normal" href="CastleProgress.TProgress.html#Max">Max</a> will be silently clamped to <a class="normal" href="CastleProgress.TProgress.html#Max">Max</a>. You can only increase it (trying to decrease it will be silently ignored, which is useful if your position information is only an approximation). In other words, setthing this property is equivalent to appropriate <a class="normal" href="CastleProgress.TProgress.html#Step">Step</a> call.</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="Max"></a><code>property <b>Max</b>: Cardinal read FMax;</code></td>
</tr>
<tr><td colspan="2">
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="Title"></a><code>property <b>Title</b>: string read FTitle;</code></td>
</tr>
<tr><td colspan="2">
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="Active"></a><code>property <b>Active</b>: boolean read FActive;</code></td>
</tr>
<tr><td colspan="2">
<p>
Are we between Init and Fini calls. Init changes Active to true, Fini changes Active to false.</p>
</td></tr>
</table>
<!-- Piwik -->
<script type="text/javascript">
var _paq = _paq || [];
_paq.push(["trackPageView"]);
_paq.push(["enableLinkTracking"]);
(function() {
var u=(("https:" == document.location.protocol) ? "https" : "http") + "://michalis.ii.uni.wroc.pl/piwik-castle-engine/";
_paq.push(["setTrackerUrl", u+"piwik.php"]);
_paq.push(["setSiteId", "1"]);
var d=document, g=d.createElement("script"), s=d.getElementsByTagName("script")[0]; g.type="text/javascript";
g.defer=true; g.async=true; g.src=u+"piwik.js"; s.parentNode.insertBefore(g,s);
})();
</script>
<!-- End Piwik Code -->
<noscript>
<!-- Piwik Image Tracker -->
<img src="http://michalis.ii.uni.wroc.pl/piwik-castle-engine/piwik.php?idsite=1&rec=1" style="border:0" alt="" />
<!-- End Piwik -->
</noscript>
<hr noshade size="1"><span class="appinfo"><em>Generated by <a href="http://pasdoc.sourceforge.net/">PasDoc 0.13.0</a> on 2015-06-15 04:43:11</em>
</span>
</td></tr></table></body></html>
|
