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
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head>
<!--
---- (c) Copyright 2002-2010 by Lutz Sammer, Russell Smith
---- This program is free software; you can redistribute it and/or modify
---- it under the terms of the GNU General Public License as published by
---- the Free Software Foundation; only version 2 of the License.
----
---- This program is distributed in the hope that it will be useful,
---- but WITHOUT ANY WARRANTY; without even the implied warranty of
---- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
---- GNU General Public License for more details.
----
---- You should have received a copy of the GNU General Public License
---- along with this program; if not, write to the Free Software
---- Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
---- 02111-1307, USA.
-->
<title>Bos Wars Scripting API: User Interface (UI)</title>
<meta http-equiv="Content-Type" content="text/html; CHARSET=iso-8859-1">
<link rel="stylesheet" type="text/css" href="scripts.css">
</head>
<body>
<h1>Bos Wars Scripting API: User Interface (UI)</h1>
<hr>
<a href="../index.html">Bos Wars</a>
<a href="../faq.html">FAQ</a>
<a href="triggers.html">PREV</a>
<a href="unittype.html">NEXT</a>
<a href="index.html">LUA Index</a>
<hr>
<a href="#CColor">CColor</a>
<a href="#CFontColor">CFontColor</a>
<a href="#CGraphic">CGraphic</a>
<a href="#CResourceInfo">CResourceInfo</a>
<a href="#DefineButton">DefineButton</a>
<a href="#DefineButtonStyle">DefineButtonStyle</a>
<a href="#DefineCursor">DefineCursor</a>
<a href="#DefineViewports">DefineViewports</a>
<a href="#HandleCommandKey">HandleCommandKey</a>
<a href="#MaxFontColors">MaxFontColors</a>
<a href="#SetGameCursor">SetGameCursor</a>
<a href="#text_formatting">text formatting</a>
<a href="#UI">UI</a>
<hr>
<h2>Intro - Introduction to UI functions and variables</h2>
Everything around the user interface.
<h2>Conceptual</h2>
<a name="text_formatting"></a>
<h3>Text formatting</h3>
<p>When the engine displays text on the screen, it recognizes the
following format codes.</p>
<dl>
<dt>"~~"</dt>
<dd>Displays a single "~" character.</dd>
<dt>"~!"</dt>
<dd>Marks the following character as a hot key
and draws it in a different color,
usually <a href="#UI.ReverseFontColor">UI.ReverseFontColor</a>.
Highlighting works even in those widgets that do not support hot
keys.</dd>
<dt>"~<" and "~>"</dt>
<dd>Marks the text between these strings as a hot key and draws it
in a different color. Use this if the name of the hot key is
multiple characters long, e.g. "Cancel (~<Esc~>)"
or "Help (~<F1~>)". If a translation to another language
changes the name of the Esc key, then the engine will recognize
both the "Esc" name and the translated name as referring to that
key.</dd>
<dt>"~<var>color</var>~" and "~>"</dt>
<dd>Displays the text between these strings with the specified
color, if such a color name has been defined with
<a href="#CFontColor.New">CFontColor:New</a>.
For example, "the ~red~original~> sin" would display
"the original sin", where "original" would be red.</dd>
</dl>
<h2>Functions</h2>
<a name="DefineButton"></a>
<h3>DefineButton({tag1 = value1, tag2 value2, ...})</h3>
Define a button in the button panel shown during the game.
Possible tags:
<dl>
<dt id="DefineButton.Pos">Pos = number</dt>
<dd>The position in which the button will appear in the button panel
or in the pie menu.
<pre>
0 1 2
3 4 5
6 7 8
</pre>
</dd>
<dt id="DefineButton.Level">Level = number</dt>
<dd>Visible when in this button level (0 default, 9 cancel-only).
<p>The engine normally returns to button
level 0 when the player selects a unit. Level 0 is also the default for
buttons that you define without explicitly specifying Level = number.</p>
<p>Button level 9 should contain only a Cancel
button (<a href="#DefineButton.Action.cancel">Action = "cancel"</a>).
The engine selects level 9 when it expects the player to choose
a target location or a target unit on the map.</p></dd>
<dt id="DefineButton.Icon">Icon = "icon-name"</dt>
<dd>Name of the icon to display.
</dd>
<dt id="DefineButton.Action">Action = "action"</dt>
<dd>Action to perform when the player clicks the button.
Can be any of the following:
<dl>
<dt id="DefineButton.Action.move">"move"</dt>
<dd>The selected unit will follow the target unit or move to the
target location. In the former case, the selected unit will stop
following if it reaches the target unit.</dd>
<dt id="DefineButton.Action.stop">"stop"</dt>
<dd>The selected unit stops.
The orders queue of the selected unit is also erased.
The selected unit then waits for an order but can react by itself.</dd>
<dt id="DefineButton.Action.attack">"attack"</dt>
<dd>The selected unit will attack only the target unit, or move to
the target location and attack any opponent on the way.</dd>
<dt id="DefineButton.Action.repair">"repair"</dt>
<dd>The selected unit will repair the target unit.</dd>
<dt id="DefineButton.Action.harvest">"harvest"</dt>
<dd>The selected unit will harvest resources from the target unit.
After the target unit is destroyed, the selected unit will try to find
more resources of the same type, unless it has another order in its queue.</dd>
<dt id="DefineButton.Action.button">"button"</dt>
<dd>Switches to a different button level; changes the button panel
to show the buttons of that level.
<p>You must set <a href="#DefineButton.Value">Value</a> = number.
The engine will show the allowed buttons that have
<a href="#DefineButton.Level">Level</a> = that number.</p></dd>
<dt id="DefineButton.Action.build">"build"</dt>
<dd>The selected unit will build a new unit at the target location.
The new unit will appear on the map as soon as the selected unit
begins building it.
<p>You must set <a href="#DefineButton.Value">Value</a> = "unit-name".
This is the type of the new unit that the selected unit will build. Normally,
you would specify a <a href="unittype.html#DefineUnitType.Building">building</a>
type here.</p></dd>
<dt id="DefineButton.Action.train-unit">"train-unit"</dt>
<dd>The selected unit will train a new unit within itself.
When training completes, the new unit will appear next to the unit
that trained it, or further away if it doesn't fit any closer.
Normally, you would specify a
<a href="unittype.html#DefineUnitType.Building">building</a> type
in the <a href="#DefineButton.ForUnit">ForUnit</a> list.
<p>You must set <a href="#DefineButton.Value">Value</a> = "unit-name".
This is the type of the new unit that the selected unit will train.</p></dd>
<dt id="DefineButton.Action.patrol">"patrol"</dt>
<dd>The selected unit will patrol between target location
and its current location and attack any opponent on the way.</dd>
<dt id="DefineButton.Action.stand-ground">"stand-ground"</dt>
<dd>The selected unit will not move.
It will stay at its location until it receives a new order.
It will however fire at any opponents that come too close.</dd>
<dt id="DefineButton.Action.attack-ground">"attack-ground"</dt>
<dd>The selected unit will attack the target location.
Useful for units with <a href="magic.html#DefineMissileType.Range">splash damage</a>.</dd>
<dt id="DefineButton.Action.cast-spell">"cast-spell"</dt>
<dd>The selected unit will cast a spell.
<p>You must set <a href="#DefineButton.Value">Value</a> = "spell-ident".
This is the unique identifier of the spell, as defined with
<a href="magic.html#DefineSpell">DefineSpell</a>.</p></dd>
<dt id="DefineButton.Action.unload">"unload"</dt>
<dd>The selected unit will unload all the units that it is carrying.
Useful for unit types defined with
<a href="unittype.html#DefineUnitType.CanTransport">CanTransport</a> = true.
If the selected unit cannot move (its unit type has no move animation
defined), then the engine assumes it is a bunker, and it will unload
its inhabitants where it is.
If the selected unit can move, then the engine assumes it is a
transporter; the player must select a target location on the map,
and the transporter will unload its passengers there.
There are some exceptions to these rules.</dd>
<dt id="DefineButton.Action.cancel">"cancel"</dt>
<dd>The engine stops waiting for the player to choose a target.
The action for which the engine wants a target is not yet in the order
queue of the selected unit, so the button does not affect the unit.
This kind of cancel should be used only with
<a href="#DefineButton.Level">Level</a> = 9.</dd>
<dt id="DefineButton.Action.cancel-train-unit">"cancel-train-unit"</dt>
<dd>The selected unit stops training units. All unit-training orders
(<a href="#DefineButton.Action.train-unit">Action = "train-unit"</a>)
are erased from the order queue of the selected unit.
(In principle, if there is some other type of order in between,
then unit-training orders that follow it are not erased.
However, units that can train typically cannot do anything else.)</dd>
<dt id="DefineButton.Action.cancel-build">"cancel-build"</dt>
<dd>The selected unit stops being built and is destroyed.
Any workers who were building it are freed.</dd>
</dl>
</dd>
<dt id="DefineButton.Value">Value = arg</dt>
<dd>Optional value associated with the <a href="#DefineButton.Action">Action</a>.
</dd>
<dt id="DefineButton.Allowed">Allowed = "check-name"</dt>
<dd>Optional check to see if a button is allowed. Can be any of the following:
<dl>
<dt>"check-true"</dt>
<dd>No restriction on this button.</dd>
<dt>"check-false"</dt>
<dd>The button is forbidden. FIXME : ? to be removed. What is its usage ?</dd>
<dt>"check-units-or"</dt>
<dd>The button is allowed if the player has at least one unit of
any of the specified types.
Need <a href="#DefineButton.AllowArg">AllowArg</a> = {"unit-name1", "unit-name2"}</dd>
<dt>"check-units-and"</dt>
<dd>The button is allowed if the player has at least one unit of
each of the specified types.
Need <a href="#DefineButton.AllowArg">AllowArg</a> = {"unit-name1", "unit-name2"}</dd>
<dt>"check-network"</dt>
<dd>The button is allowed only during a network game.</dd>
<dt>"check-no-network"</dt>
<dd>The button is allowed only during a non-network game.</dd>
<dt>"check-no-work"</dt>
<dd>The button is allowed unless the selected unit is training a unit
(with <a href="#DefineButton.Action.train-unit">Action = "train-unit"</a>).</dd>
<dt>"check-attack"</dt>
<dd>The button is allowed if the selected unit can attack at all,
i.e. its unit type was defined with
<a href="unittype.html#DefineUnitType.CanAttack">CanAttack</a> = true.</dd>
</dl>
If you do not specify Allowed, then the engine decides
whether the button is allowed, based on which units the player has selected
and which <a href="#DefineButton.Action">Action</a> the button has.
For example, if the button has
<a href="#DefineButton.Action.patrol">Action = "patrol"</a>,
and the player selects a building that cannot move,
then the button is not allowed by default.
If you do specify Allowed, it overrides these default checks,
but the <a href="#DefineButton.ForUnit">ForUnit</a> list still applies.
</dd>
<dt id="DefineButton.AllowArg">AllowArg = {"arg1", ...}</dt>
<dd>Optional argument used by the allowed function.
</dd>
<dt id="DefineButton.Hint">Hint = "string"</dt>
<dd>Hint to be displayed for the button. To define a shortcut key
for the button, use the "~!", "~<", and "~>" format codes
described in <a href="#text_formatting">Text formatting</a>.
</dd>
<dt id="DefineButton.ForUnit">ForUnit = {"unit-name1", ...} or {"*"} </dt>
<dd>List of units the button applies to, or {"*"} for all units.
</dd>
</dl>
<h4>Example</h4>
<pre class="lua">
DefineButton( { Pos = 8, Level = 0, Icon = "icon-build-advanced",
Action = "button", Value = 2,
Allowed = "check-units-or", AllowArg = {"unit-elven-lumber-mill", "unit-keep"},
Hint = "BUILD AD~!VANCED STRUCTURE",
ForUnit = {"unit-peasant"} } )
</pre>
<a name="DefineButtonStyle"></a>
<h3>DefineButtonStyle(style, {tag = value, ...})</h3>
Define a button style. Possible tags:
<dl>
<dt>Size = {x, y}</dt>
<dd>Size of the button.
</dd>
<dt>Font = font-name</dt>
<dd>Name of the font to use.
</dd>
<dt>TextNormalColor = color, TextReverseColor = color</dt>
<dd>Color to use for the normal and reverse text.
</dd>
<dt>TextAlign = align</dt>
<dd>Align the text. Possible values are "Left", "Right", and "Center".
</dd>
<dt>TextPos = {posx, posy}</dt>
<dd>Set the position of the text relative to the upper left corner of the image.
</dd>
<dt>Default = {tag = value, ...}, Hover = {}, Selected = {}, Clicked = {}, Disabled = {}</dt>
<dd>Set attributes for when the mouse is over the button (Hover), the button is
Selected, Clicked, Disabled, or the Default setting. Possible tags:
<dl>
<dt>File = file</dt>
<dd>The filename.
</dd>
<dt>Size = size</dt>
<dd>The size of the image (only needed when using an image with multiple frames).
</dd>
<dt>Frame = frame</dt>
<dd>Select the frame number from an image (only needed when using an image with multiple frames).
</dd>
<dt>TextNormalColor = color, TextReverseColor = color</dt>
<dd>Color to use for the normal and reverse text (overrides the main colors).
</dd>
<dt>TextPos = {x, y}</dt>
<dd>Display the text at this position (overrides the main position).
</dd>
<dt>Border = { Color = color, Size = size}</dt>
<dd>Draw a border with the specified color and size.
</dd>
</dl>
</dd>
</dl>
<h4>Example</h4>
<pre class="lua">
DefineButtonStyle("main", {
Size = {128, 20},
Font = "game",
TextNormalColor = "yellow",
TextReverseColor = "white",
TextAlign = "Center",
TextPos = {64, 4},
Default = {
File = "ui/buttons_1.png", Size = {300, 144}, Frame = 4,
},
Hover = {
TextNormalColor = "white",
},
Selected = {
Border = {
Color = {252, 252, 0}, Size = 1,
},
},
Clicked = {
File = "ui/buttons_1.png", Size = {300, 144}, Frame = 5,
TextNormalColor = "white",
TextPos = {66, 6},
},
Disabled = {
File = "ui/buttons_1.png", Size = {300, 144}, Frame = 3,
TextNormalColor = "grey",
TextReverseColor = "grey",
},
})
</pre>
<a name="DefineCursor"></a>
<h3>DefineCursor({tag = value, ...})</h3>
Define a cursor.
<dl>
<dt>Name = "ident"</dt>
<dd>Unique identifier of the cursor, used to reference it in config files and
during startup.
</dd>
</dl>
Possible tags:
<dl>
<dt>File = "icon-file"</dt>
<dd>Path to the image graphic.</dd>
<dt>HotSpot = {x, y}</dt>
<dd>Hot spot of the cursor in pixels. Relative to the sprite origin {0, 0}. The
hot spot of a cursor is the point to which Bos Wars refers in tracking the
cursor's position.
</dd>
<dt>Size = {width, height}</dt>
<dd>Size of the cursor in pixels.</dd>
<dt>Rate = millisecond</dt>
<dd>Rate of changing the frames if using an animated cursor. The "rate" tells
the engine how many milliseconds to hold each frame of the animation.
</dd>
</dl>
Note: Name, File and Size must be filled.
<h4>Example</h4>
<pre class="lua">
DefineCursor({
Name = "cursor-cross",
File = "ui/cursors/small_green_cross.png",
HotSpot = {8, 8},
Size = {18, 18}})
</pre>
<a name="DefineViewports"></a>
<h3>DefineViewports("mode", mode, "viewport", {mapx, mapy}, ...)</h3>
Define the viewports. Only used in savegames, but could be useful for
scenarios.
<dl>
<dt>"mode", number</dt>
<dd>Number corresponding to the viewport mode. See the ViewportMode enum. FIXME</dd>
<dt>"viewport", {mapx, mapy}</dt>
<dd>X, Y coordinate of the map tile.
</dd>
</dl>
<h4>Example</h4>
<pre class="lua">
-- Defines the viewports to use mode 1 (split horizontal) with the first
-- viewport having map coordinates 82,31 and the second having coordinates 64,31.
DefineViewports("mode", 1, "viewport", {82, 31},
"viewport", {64, 31})
</pre>
<a name="SetGameCursor"></a>
<h3>SetGameCursor("cursor-ident")</h3>
Set the game cursor.
<dl>
<dt>"cursor-ident"</dt>
<dd>Unique identifier of the cursor.</dd>
</dl>
<h4>Example</h4>
<pre class="lua">
-- Set the game cursor to 'cursor-point'.
SetGameCursor("cursor-point")
</pre>
<a name="HandleCommandKey"></a>
<h3>HandleCommandKey("key", ctrl, alt, shift)</h3>
<p>The Lua script must define this function. The engine calls it when
the user presses a key that the engine does not handle on its own, and
no menu is open. The engine can call this function during the game,
in the map editor, or in the patch editor. To handle different keys
in different situations, the Lua script can redefine this function
when the user enters or leaves an editor.</p>
<dl>
<dt>"key"</dt>
<dd>The name of the key that the user pressed; for example, "a" or
"escape". The name does not depend on which the language the user
selected.</dd>
<dt>ctrl</dt>
<dd>true if the user pressed the Control key too, false if not.</dd>
<dt>alt</dt>
<dd>true if the user pressed the Alt key too, false if not.</dd>
<dt>shift</dt>
<dd>true if the user pressed the Shift key too, false if not.</dd>
<dt><i>RETURNS</i></dt>
<dd>true if HandleCommandKey handled the key, false if the engine
should try to handle the key in some other way.</dd>
</dl>
<h2>Variables</h2>
<a name="UI"></a>
<h3>UI</h3>
<p>This variable refers to an object that has at least the following properties:
<a href="#UI.ButtonPanel.ShowCommandKey">ButtonPanel.ShowCommandKey</a>
<a href="#UI.ReverseFontColor">ReverseFontColor</a>
<a href="#UI.Resources">Resources</a>
</p>
<p>Do not change the UI variable itself from Lua, even
though the engine may allow that.</p>
<a name="UI.ButtonPanel.ShowCommandKey"></a>
<h4>UI.ButtonPanel.ShowCommandKey = boolean</h4>
<p>Enable/disable the display of the command keys in buttons.</p>
<a name="UI.ReverseFontColor"></a>
<h4>UI.ReverseFontColor = string</h4>
<p>The name of the font color generally used for highlighting
in <a href="#text_formatting">text formatting</a>.
The font color must be defined with
<a href="#CFontColor.New">CFontColor:New</a>.</p>
<a name="UI.Resources"></a>
<h4>UI.Resources = table</h4>
<p>How the engine displays the resource costs of a command.
This table contains a <a href="#CResourceInfo">CResourceInfo</a>
instance for each type of resource. The indices of the table are
<a href="config.html#resource_type_identifiers">resource type identifiers</a>,
i.e. integers between 0 and <a href="config.html#MaxCosts">MaxCosts</a>-1
(even though indices typically start from 1 in Lua).</p>
<h2>Types</h2>
<a name="CColor"></a>
<h3>CColor</h3>
<p>The CColor type represents an RGBA color.</p>
<p>In the following subsections, <var>color</var> denotes
a CColor instance.</p>
<h4>CColor([r], [g], [b], [a])</h4>
<p>Constructs a <a href="#CColor">CColor</a> instance with the
specified Red, Green, Blue, and Alpha component values.
All arguments are optional.</p>
<h4><var>color</var>.R</h4>
<p>The red component, between 0 and 255.</p>
<h4><var>color</var>.G</h4>
<p>The green component, between 0 and 255.</p>
<h4><var>color</var>.B</h4>
<p>The blue component, between 0 and 255.</p>
<h4><var>color</var>.A</h4>
<p>The alpha component, between 0 and 255.
Not premultiplied.</p>
<p>Currently, the engine ignores the alpha component
of all CColor instances that Lua code can access:</p>
<ul>
<li><a href="#CFontColor.Colors"><var>fontColor</var>.Colors</a></li>
<li>UI.ButtonPanel.AutoCastBorderColorRGB</li>
<li>UI.CompletedBarColorRGB</li>
</ul>
<a name="CFontColor"></a>
<h3>CFontColor</h3>
<p>Each CFontColor instance represents a named set of colors for use
in <a href="#text_formatting">text formatting</a>.</p>
<p>In the following subsections, <var>fontColor</var> denotes
a CFontColor instance.</p>
<a name="CFontColor.Colors"></a>
<h4><var>fontColor</var>.Colors</h4>
<p>An array of <a href="#CColor">CColor</a> instances.
There are <a href="#MaxFontColors">MaxFontColors</a> elements in the array.
The engine ignores the alpha component of these CColor instances.</p>
<a name="CFontColor.Get"></a>
<h4>CFontColor:Get("name")</h4>
<p>Finds a font color by name.
Returns a <a href="#CFontColor">CFontColor</a> instance if found.
If no such font color has been defined, which indicates a bug,
then this function returns nil instead.</p>
<a name="CFontColor.New"></a>
<h4>CFontColor:New("name")</h4>
<p>Finds a font color by name, or allocates a new one.
Returns a <a href="#CFontColor">CFontColor</a> instance.
If it is a new one, then its <a href="#CFontColor.Colors">Colors</a>
array is all black, so you should set that before you use the
font color in <a href="#text_formatting">text formatting</a>.</p>
<a name="MaxFontColors"></a>
<h4>MaxFontColors</h4>
<p>This constant integer is the number of elements in the
<a href="#CFontColor.Colors">Colors</a> array in CFontColor
instances.</p>
<a name="CResourceInfo"></a>
<h3>CResourceInfo</h3>
<p>In the <a href="#UI.Resources">UI.Resources</a> table,
there is one CResourceInfo instance for each type of resource.
These objects control how the engine displays the resource costs of
a command. Each CResourceInfo instance has the following properties:</p>
<dl>
<dt><a name="CResourceInfo.G">G</a></dt>
<dd>The <a href="#CGraphic">CGraphic</a> instance
that contains the resource icon.</dd>
<dt><a name="CResourceInfo.IconFrame">IconFrame</a></dt>
<dd>The frame number of the resource icon within the graphic.
See <a href="unittype.html#frame_numbers">Frame numbers and flipping</a>.</dd>
<dt class="obsolete"><a name="CResourceInfo.IconX">IconX</a></dt>
<dd class="obsolete"><em>Obsolete since r8638 (2007-03-28):
The coordinates are hardcoded.</em>
The X coordinate of the resource icon on the screen,
for resources held by the player.</dd>
<dt class="obsolete"><a name="CResourceInfo.IconY">IconY</a></dt>
<dd class="obsolete"><em>Obsolete since r8638 (2007-03-28):
The coordinates are hardcoded.</em>
The Y coordinate of the resource icon on the screen,
for resources held by the player.</dd>
<dt class="obsolete"><a name="CResourceInfo.TextX">TextX</a></dt>
<dd class="obsolete"><em>Obsolete since r8638 (2007-03-28):
The coordinates are hardcoded.</em>
The X coordinate of the text that describes the amount
of resource held by the player.</dd>
<dt class="obsolete"><a name="CResourceInfo.TextY">TextY</a></dt>
<dd class="obsolete"><em>Obsolete since r8638 (2007-03-28):
The coordinates are hardcoded.</em>
The Y coordinate of the text that describes the amount
of resource held by the player.</dd>
</dl>
<p>These properties can be accessed with expressions like
<code>UI.Resources[EnergyCost].G</code>.</p>
<a name="CGraphic"></a>
<h3>CGraphic</h3>
<p>A CGraphic instance is a graphic image that can be loaded from a
file and then displayed on the screen.</p>
<p>In the following subsections, <var>graphic</var> denotes
a CGraphic instance.</p>
<a name="CGraphic.New"></a>
<h4>CGraphic:New("filename", [width], [height])</h4>
<p>Creates a CGraphic instance that refers to the specified image file,
unless one exists already.</p>
<dl>
<dt>"filename"</dt>
<dd>The name of the file from which
<a href="#CGraphic.Load">CGraphic::Load</a> will load the graphic.</dd>
<dt>width</dt>
<dd>The width of each frame in the graphic,
or 0 (default) to use the whole graphic as just one frame.</dd>
<dt>height</dt>
<dd>The height of each frame in the graphic,
or 0 (default) to use the whole graphic as just one frame.</dd>
<dt><i>RETURNS</i></dt>
<dd>A CGraphic instance that refers to the specified image file.
If one had already been created, then CGraphic::New returns that
and increments its reference count; otherwise, CGraphic::New
creates a new CGraphic instance.
In either case, <a href="#CGraphic.Free">CGraphic:Free</a>
will have to be called.</dd>
</dl>
<a name="CGraphic.Free"></a>
<h4>CGraphic:Free(graphic)</h4>
<p>Decrements the reference count of a CGraphic instance,
and frees it if the reference count becomes zero.</p>
<p>The reference counts of CGraphic instances are not currently
connected to Lua garbage collection. CGraphic:Free must be
called explicitly. If a CGraphic instance is used after it
has been freed, the engine will probably crash.</p>
<dl>
<dt>graphic</dt>
<dd>The CGraphic instance that the method should free.</dd>
<dt><i>RETURNS</i></dt>
<dd>Nothing.</dd>
</dl>
<a name="CGraphic.Load"></a>
<h4><var>graphic</var>:Load()</h4>
<p>Loads the graphic from the image file whose name was given
to <a href="#CGraphic.New">CGraphic:New</a>, unless it has
already been loaded.</p>
<dl>
<dt>graphic</dt>
<dd>The CGraphic instance that the method should load.</dd>
<dt><i>RETURNS</i></dt>
<dd>Nothing.</dd>
</dl>
<a name="CGraphic.Resize"></a>
<h4><var>graphic</var>:Resize(width, height)</h4>
<p>Resizes the graphic to the specified size.
Because <a href="#CGraphic.New">CGraphic:New</a> returns
the same CGraphic instance when given the same file name,
resizing can affect other uses of the same graphic.
To prevent such problems, you should use this method
only on graphics that are displayed in one place at a time
and are always resized before use.</p>
<dl>
<dt>graphic</dt>
<dd>The CGraphic instance that the method should resize.</dd>
<dt>width</dt>
<dd>The new width of the graphic, in pixels.</dd>
<dt>height</dt>
<dd>The new height of the graphic, in pixels.</dd>
<dt><i>RETURNS</i></dt>
<dd>Nothing.</dd>
</dl>
<hr>
All trademarks and copyrights on this page are owned by their respective owners.
<address>(c) 2002-2010 by <a href="http://boswars.org">
The Bos Wars Project</a></address></body></html>
|
