Debian Codegraph @

doc/scripts/ui.html

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 <html><head>
3 <!--
4 ---- (c) Copyright 2002-2010 by Lutz Sammer, Russell Smith
5
6 ---- This program is free software; you can redistribute it and/or modify
7 ---- it under the terms of the GNU General Public License as published by
8 ---- the Free Software Foundation; only version 2 of the License.
9 ----
10 ---- This program is distributed in the hope that it will be useful,
11 ---- but WITHOUT ANY WARRANTY; without even the implied warranty of
12 ---- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 ---- GNU General Public License for more details.
14 ----
15 ---- You should have received a copy of the GNU General Public License
16 ---- along with this program; if not, write to the Free Software
17 ---- Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
18 ---- 02111-1307, USA.
19 -->
20 <title>Bos Wars Scripting API: User Interface (UI)</title>
21 <meta http-equiv="Content-Type" content="text/html; CHARSET=iso-8859-1">
22 <link rel="stylesheet" type="text/css" href="scripts.css">
23 </head>
24 <body>
25 <h1>Bos Wars Scripting API: User Interface (UI)</h1>
26 <hr>
27 <a href="../index.html">Bos Wars</a>
28 <a href="../faq.html">FAQ</a>
29 <a href="triggers.html">PREV</a>
30 <a href="unittype.html">NEXT</a>
31 <a href="index.html">LUA Index</a>
32 <hr>
33 <a href="#CColor">CColor</a>
34 <a href="#CFontColor">CFontColor</a>
35 <a href="#CGraphic">CGraphic</a>
36 <a href="#CResourceInfo">CResourceInfo</a>
37 <a href="#DefineButton">DefineButton</a>
38 <a href="#DefineButtonStyle">DefineButtonStyle</a>
39 <a href="#DefineCursor">DefineCursor</a>
40 <a href="#DefineViewports">DefineViewports</a>
41 <a href="#HandleCommandKey">HandleCommandKey</a>
42 <a href="#MaxFontColors">MaxFontColors</a>
43 <a href="#SetGameCursor">SetGameCursor</a>
44 <a href="#text_formatting">text formatting</a>
45 <a href="#UI">UI</a>
46 <hr>
47 <h2>Intro - Introduction to UI functions and variables</h2>
48
49 Everything around the user interface.
50
51 <h2>Conceptual</h2>
52
53 <a name="text_formatting"></a>
54 <h3>Text formatting</h3>
55
56 <p>When the engine displays text on the screen, it recognizes the
57 following format codes.</p>
58
59 <dl>
60 <dt>"~~"</dt>
61 <dd>Displays a single "~" character.</dd>
62 <dt>"~!"</dt>
63 <dd>Marks the following character as a hot key
64 and draws it in a different color,
65 usually <a href="#UI.ReverseFontColor">UI.ReverseFontColor</a>.
66 Highlighting works even in those widgets that do not support hot
67 keys.</dd>
68 <dt>"~&lt;" and "~&gt;"</dt>
69 <dd>Marks the text between these strings as a hot key and draws it
70 in a different color. Use this if the name of the hot key is
71 multiple characters long, e.g. "Cancel (~&lt;Esc~&gt;)"
72 or "Help (~&lt;F1~&gt;)". If a translation to another language
73 changes the name of the Esc key, then the engine will recognize
74 both the "Esc" name and the translated name as referring to that
75 key.</dd>
76 <dt>"~<var>color</var>~" and "~&gt;"</dt>
77 <dd>Displays the text between these strings with the specified
78 color, if such a color name has been defined with
79 <a href="#CFontColor.New">CFontColor:New</a>.
80 For example, "the ~red~original~&gt; sin" would display
81 "the original sin", where "original" would be red.</dd>
82 </dl>
83
84 <h2>Functions</h2>
85
86 <a name="DefineButton"></a>
87 <h3>DefineButton({tag1 = value1, tag2 value2, ...})</h3>
88
89 Define a button in the button panel shown during the game.
90 Possible tags:
91
92 <dl>
93 <dt id="DefineButton.Pos">Pos = number</dt>
94 <dd>The position in which the button will appear in the button panel
95 or in the pie menu.
96 <pre>
97 0 1 2
98 3 4 5
99 6 7 8
100 </pre>
101 </dd>
102 <dt id="DefineButton.Level">Level = number</dt>
103 <dd>Visible when in this button level (0 default, 9 cancel-only).
104 <p>The engine normally returns to button
105 level 0 when the player selects a unit. Level 0 is also the default for
106 buttons that you define without explicitly specifying Level = number.</p>
107 <p>Button level 9 should contain only a Cancel
108 button (<a href="#DefineButton.Action.cancel">Action = "cancel"</a>).
109 The engine selects level 9 when it expects the player to choose
110 a target location or a target unit on the map.</p></dd>
111 <dt id="DefineButton.Icon">Icon = "icon-name"</dt>
112 <dd>Name of the icon to display.
113 </dd>
114 <dt id="DefineButton.Action">Action = "action"</dt>
115 <dd>Action to perform when the player clicks the button.
116 Can be any of the following:
117 <dl>
118 <dt id="DefineButton.Action.move">"move"</dt>
119 <dd>The selected unit will follow the target unit or move to the
120 target location. In the former case, the selected unit will stop
121 following if it reaches the target unit.</dd>
122 <dt id="DefineButton.Action.stop">"stop"</dt>
123 <dd>The selected unit stops.
124 The orders queue of the selected unit is also erased.
125 The selected unit then waits for an order but can react by itself.</dd>
126 <dt id="DefineButton.Action.attack">"attack"</dt>
127 <dd>The selected unit will attack only the target unit, or move to
128 the target location and attack any opponent on the way.</dd>
129 <dt id="DefineButton.Action.repair">"repair"</dt>
130 <dd>The selected unit will repair the target unit.</dd>
131 <dt id="DefineButton.Action.harvest">"harvest"</dt>
132 <dd>The selected unit will harvest resources from the target unit.
133 After the target unit is destroyed, the selected unit will try to find
134 more resources of the same type, unless it has another order in its queue.</dd>
135 <dt id="DefineButton.Action.button">"button"</dt>
136 <dd>Switches to a different button level; changes the button panel
137 to show the buttons of that level.
138 <p>You must set <a href="#DefineButton.Value">Value</a> = number.
139 The engine will show the allowed buttons that have
140 <a href="#DefineButton.Level">Level</a> = that number.</p></dd>
141 <dt id="DefineButton.Action.build">"build"</dt>
142 <dd>The selected unit will build a new unit at the target location.
143 The new unit will appear on the map as soon as the selected unit
144 begins building it.
145 <p>You must set <a href="#DefineButton.Value">Value</a> = "unit-name".
146 This is the type of the new unit that the selected unit will build. Normally,
147 you would specify a <a href="unittype.html#DefineUnitType.Building">building</a>
148 type here.</p></dd>
149 <dt id="DefineButton.Action.train-unit">"train-unit"</dt>
150 <dd>The selected unit will train a new unit within itself.
151 When training completes, the new unit will appear next to the unit
152 that trained it, or further away if it doesn't fit any closer.
153 Normally, you would specify a
154 <a href="unittype.html#DefineUnitType.Building">building</a> type
155 in the <a href="#DefineButton.ForUnit">ForUnit</a> list.
156 <p>You must set <a href="#DefineButton.Value">Value</a> = "unit-name".
157 This is the type of the new unit that the selected unit will train.</p></dd>
158 <dt id="DefineButton.Action.patrol">"patrol"</dt>
159 <dd>The selected unit will patrol between target location
160 and its current location and attack any opponent on the way.</dd>
161 <dt id="DefineButton.Action.stand-ground">"stand-ground"</dt>
162 <dd>The selected unit will not move.
163 It will stay at its location until it receives a new order.
164 It will however fire at any opponents that come too close.</dd>
165 <dt id="DefineButton.Action.attack-ground">"attack-ground"</dt>
166 <dd>The selected unit will attack the target location.
167 Useful for units with <a href="magic.html#DefineMissileType.Range">splash damage</a>.</dd>
168 <dt id="DefineButton.Action.cast-spell">"cast-spell"</dt>
169 <dd>The selected unit will cast a spell.
170 <p>You must set <a href="#DefineButton.Value">Value</a> = "spell-ident".
171 This is the unique identifier of the spell, as defined with
172 <a href="magic.html#DefineSpell">DefineSpell</a>.</p></dd>
173 <dt id="DefineButton.Action.unload">"unload"</dt>
174 <dd>The selected unit will unload all the units that it is carrying.
175 Useful for unit types defined with
176 <a href="unittype.html#DefineUnitType.CanTransport">CanTransport</a> = true.
177 If the selected unit cannot move (its unit type has no move animation
178 defined), then the engine assumes it is a bunker, and it will unload
179 its inhabitants where it is.
180 If the selected unit can move, then the engine assumes it is a
181 transporter; the player must select a target location on the map,
182 and the transporter will unload its passengers there.
183 There are some exceptions to these rules.</dd>
184 <dt id="DefineButton.Action.cancel">"cancel"</dt>
185 <dd>The engine stops waiting for the player to choose a target.
186 The action for which the engine wants a target is not yet in the order
187 queue of the selected unit, so the button does not affect the unit.
188 This kind of cancel should be used only with
189 <a href="#DefineButton.Level">Level</a> = 9.</dd>
190 <dt id="DefineButton.Action.cancel-train-unit">"cancel-train-unit"</dt>
191 <dd>The selected unit stops training units. All unit-training orders
192 (<a href="#DefineButton.Action.train-unit">Action = "train-unit"</a>)
193 are erased from the order queue of the selected unit.
194 (In principle, if there is some other type of order in between,
195 then unit-training orders that follow it are not erased.
196 However, units that can train typically cannot do anything else.)</dd>
197 <dt id="DefineButton.Action.cancel-build">"cancel-build"</dt>
198 <dd>The selected unit stops being built and is destroyed.
199 Any workers who were building it are freed.</dd>
200 </dl>
201 </dd>
202 <dt id="DefineButton.Value">Value = arg</dt>
203 <dd>Optional value associated with the <a href="#DefineButton.Action">Action</a>.
204 </dd>
205 <dt id="DefineButton.Allowed">Allowed = "check-name"</dt>
206 <dd>Optional check to see if a button is allowed. Can be any of the following:
207 <dl>
208 <dt>"check-true"</dt>
209 <dd>No restriction on this button.</dd>
210 <dt>"check-false"</dt>
211 <dd>The button is forbidden. FIXME : ? to be removed. What is its usage ?</dd>
212 <dt>"check-units-or"</dt>
213 <dd>The button is allowed if the player has at least one unit of
214 any of the specified types.
215 Need <a href="#DefineButton.AllowArg">AllowArg</a> = {"unit-name1", "unit-name2"}</dd>
216 <dt>"check-units-and"</dt>
217 <dd>The button is allowed if the player has at least one unit of
218 each of the specified types.
219 Need <a href="#DefineButton.AllowArg">AllowArg</a> = {"unit-name1", "unit-name2"}</dd>
220 <dt>"check-network"</dt>
221 <dd>The button is allowed only during a network game.</dd>
222 <dt>"check-no-network"</dt>
223 <dd>The button is allowed only during a non-network game.</dd>
224 <dt>"check-no-work"</dt>
225 <dd>The button is allowed unless the selected unit is training a unit
226 (with <a href="#DefineButton.Action.train-unit">Action = "train-unit"</a>).</dd>
227 <dt>"check-attack"</dt>
228 <dd>The button is allowed if the selected unit can attack at all,
229 i.e. its unit type was defined with
230 <a href="unittype.html#DefineUnitType.CanAttack">CanAttack</a> = true.</dd>
231 </dl>
232 If you do not specify Allowed, then the engine decides
233 whether the button is allowed, based on which units the player has selected
234 and which <a href="#DefineButton.Action">Action</a> the button has.
235 For example, if the button has
236 <a href="#DefineButton.Action.patrol">Action = "patrol"</a>,
237 and the player selects a building that cannot move,
238 then the button is not allowed by default.
239 If you do specify Allowed, it overrides these default checks,
240 but the <a href="#DefineButton.ForUnit">ForUnit</a> list still applies.
241 </dd>
242 <dt id="DefineButton.AllowArg">AllowArg = {"arg1", ...}</dt>
243 <dd>Optional argument used by the allowed function.
244 </dd>
245 <dt id="DefineButton.Hint">Hint = "string"</dt>
246 <dd>Hint to be displayed for the button. To define a shortcut key
247 for the button, use the "~!", "~&lt;", and "~&gt;" format codes
248 described in <a href="#text_formatting">Text formatting</a>.
249 </dd>
250 <dt id="DefineButton.ForUnit">ForUnit = {"unit-name1", ...} or {"*"} </dt>
251 <dd>List of units the button applies to, or {"*"} for all units.
252 </dd>
253 </dl>
254
255 <h4>Example</h4>
256
257 <pre class="lua">
258 DefineButton( { Pos = 8, Level = 0, Icon = "icon-build-advanced",
259 Action = "button", Value = 2,
260 Allowed = "check-units-or", AllowArg = {"unit-elven-lumber-mill", "unit-keep"},
261 Hint = "BUILD AD~!VANCED STRUCTURE",
262 ForUnit = {"unit-peasant"} } )
263 </pre>
264
265 <a name="DefineButtonStyle"></a>
266 <h3>DefineButtonStyle(style, {tag = value, ...})</h3>
267
268 Define a button style. Possible tags:
269
270 <dl>
271 <dt>Size = {x, y}</dt>
272 <dd>Size of the button.
273 </dd>
274 <dt>Font = font-name</dt>
275 <dd>Name of the font to use.
276 </dd>
277 <dt>TextNormalColor = color, TextReverseColor = color</dt>
278 <dd>Color to use for the normal and reverse text.
279 </dd>
280 <dt>TextAlign = align</dt>
281 <dd>Align the text. Possible values are "Left", "Right", and "Center".
282 </dd>
283 <dt>TextPos = {posx, posy}</dt>
284 <dd>Set the position of the text relative to the upper left corner of the image.
285 </dd>
286 <dt>Default = {tag = value, ...}, Hover = {}, Selected = {}, Clicked = {}, Disabled = {}</dt>
287 <dd>Set attributes for when the mouse is over the button (Hover), the button is
288 Selected, Clicked, Disabled, or the Default setting. Possible tags:
289 <dl>
290 <dt>File = file</dt>
291 <dd>The filename.
292 </dd>
293 <dt>Size = size</dt>
294 <dd>The size of the image (only needed when using an image with multiple frames).
295 </dd>
296 <dt>Frame = frame</dt>
297 <dd>Select the frame number from an image (only needed when using an image with multiple frames).
298 </dd>
299 <dt>TextNormalColor = color, TextReverseColor = color</dt>
300 <dd>Color to use for the normal and reverse text (overrides the main colors).
301 </dd>
302 <dt>TextPos = {x, y}</dt>
303 <dd>Display the text at this position (overrides the main position).
304 </dd>
305 <dt>Border = { Color = color, Size = size}</dt>
306 <dd>Draw a border with the specified color and size.
307 </dd>
308 </dl>
309 </dd>
310 </dl>
311
312 <h4>Example</h4>
313
314 <pre class="lua">
315 DefineButtonStyle("main", {
316 Size = {128, 20},
317 Font = "game",
318 TextNormalColor = "yellow",
319 TextReverseColor = "white",
320 TextAlign = "Center",
321 TextPos = {64, 4},
322 Default = {
323 File = "ui/buttons_1.png", Size = {300, 144}, Frame = 4,
324 },
325 Hover = {
326 TextNormalColor = "white",
327 },
328 Selected = {
329 Border = {
330 Color = {252, 252, 0}, Size = 1,
331 },
332 },
333 Clicked = {
334 File = "ui/buttons_1.png", Size = {300, 144}, Frame = 5,
335 TextNormalColor = "white",
336 TextPos = {66, 6},
337 },
338 Disabled = {
339 File = "ui/buttons_1.png", Size = {300, 144}, Frame = 3,
340 TextNormalColor = "grey",
341 TextReverseColor = "grey",
342 },
343 })
344 </pre>
345
346 <a name="DefineCursor"></a>
347 <h3>DefineCursor({tag = value, ...})</h3>
348
349 Define a cursor.
350
351 <dl>
352 <dt>Name = "ident"</dt>
353 <dd>Unique identifier of the cursor, used to reference it in config files and
354 during startup.
355 </dd>
356 </dl>
357 Possible tags:
358 <dl>
359 <dt>File = "icon-file"</dt>
360 <dd>Path to the image graphic.</dd>
361 <dt>HotSpot = {x, y}</dt>
362 <dd>Hot spot of the cursor in pixels. Relative to the sprite origin {0, 0}. The
363 hot spot of a cursor is the point to which Bos Wars refers in tracking the
364 cursor's position.
365 </dd>
366 <dt>Size = {width, height}</dt>
367 <dd>Size of the cursor in pixels.</dd>
368 <dt>Rate = millisecond</dt>
369 <dd>Rate of changing the frames if using an animated cursor. The "rate" tells
370 the engine how many milliseconds to hold each frame of the animation.
371 </dd>
372 </dl>
373
374 Note: Name, File and Size must be filled.
375
376 <h4>Example</h4>
377
378 <pre class="lua">
379 DefineCursor({
380 Name = "cursor-cross",
381 File = "ui/cursors/small_green_cross.png",
382 HotSpot = {8, 8},
383 Size = {18, 18}})
384 </pre>
385
386 <a name="DefineViewports"></a>
387 <h3>DefineViewports("mode", mode, "viewport", {mapx, mapy}, ...)</h3>
388
389 Define the viewports. Only used in savegames, but could be useful for
390 scenarios.
391
392 <dl>
393 <dt>"mode", number</dt>
394 <dd>Number corresponding to the viewport mode. See the ViewportMode enum. FIXME</dd>
395 <dt>"viewport", {mapx, mapy}</dt>
396 <dd>X, Y coordinate of the map tile.
397 </dd>
398 </dl>
399
400 <h4>Example</h4>
401
402 <pre class="lua">
403 -- Defines the viewports to use mode 1 (split horizontal) with the first
404 -- viewport having map coordinates 82,31 and the second having coordinates 64,31.
405 DefineViewports("mode", 1, "viewport", {82, 31},
406 "viewport", {64, 31})
407 </pre>
408
409 <a name="SetGameCursor"></a>
410 <h3>SetGameCursor("cursor-ident")</h3>
411 Set the game cursor.
412 <dl>
413 <dt>"cursor-ident"</dt>
414 <dd>Unique identifier of the cursor.</dd>
415 </dl>
416
417 <h4>Example</h4>
418
419 <pre class="lua">
420 -- Set the game cursor to 'cursor-point'.
421 SetGameCursor("cursor-point")
422 </pre>
423
424 <a name="HandleCommandKey"></a>
425 <h3>HandleCommandKey("key", ctrl, alt, shift)</h3>
426
427 <p>The Lua script must define this function. The engine calls it when
428 the user presses a key that the engine does not handle on its own, and
429 no menu is open. The engine can call this function during the game,
430 in the map editor, or in the patch editor. To handle different keys
431 in different situations, the Lua script can redefine this function
432 when the user enters or leaves an editor.</p>
433
434 <dl>
435 <dt>"key"</dt>
436 <dd>The name of the key that the user pressed; for example, "a" or
437 "escape". The name does not depend on which the language the user
438 selected.</dd>
439 <dt>ctrl</dt>
440 <dd>true if the user pressed the Control key too, false if not.</dd>
441 <dt>alt</dt>
442 <dd>true if the user pressed the Alt key too, false if not.</dd>
443 <dt>shift</dt>
444 <dd>true if the user pressed the Shift key too, false if not.</dd>
445 <dt><i>RETURNS</i></dt>
446 <dd>true if HandleCommandKey handled the key, false if the engine
447 should try to handle the key in some other way.</dd>
448 </dl>
449
450 <h2>Variables</h2>
451
452 <a name="UI"></a>
453 <h3>UI</h3>
454
455 <p>This variable refers to an object that has at least the following properties:
456 <a href="#UI.ButtonPanel.ShowCommandKey">ButtonPanel.ShowCommandKey</a>
457 <a href="#UI.ReverseFontColor">ReverseFontColor</a>
458 <a href="#UI.Resources">Resources</a>
459 </p>
460
461 <p>Do not change the UI variable itself from Lua, even
462 though the engine may allow that.</p>
463
464 <a name="UI.ButtonPanel.ShowCommandKey"></a>
465 <h4>UI.ButtonPanel.ShowCommandKey = boolean</h4>
466
467 <p>Enable/disable the display of the command keys in buttons.</p>
468
469 <a name="UI.ReverseFontColor"></a>
470 <h4>UI.ReverseFontColor = string</h4>
471
472 <p>The name of the font color generally used for highlighting
473 in <a href="#text_formatting">text formatting</a>.
474 The font color must be defined with
475 <a href="#CFontColor.New">CFontColor:New</a>.</p>
476
477 <a name="UI.Resources"></a>
478 <h4>UI.Resources = table</h4>
479
480 <p>How the engine displays the resource costs of a command.
481 This table contains a <a href="#CResourceInfo">CResourceInfo</a>
482 instance for each type of resource. The indices of the table are
483 <a href="config.html#resource_type_identifiers">resource type identifiers</a>,
484 i.e. integers between 0 and <a href="config.html#MaxCosts">MaxCosts</a>-1
485 (even though indices typically start from 1 in Lua).</p>
486
487 <h2>Types</h2>
488
489 <a name="CColor"></a>
490 <h3>CColor</h3>
491
492 <p>The CColor type represents an RGBA color.</p>
493
494 <p>In the following subsections, <var>color</var> denotes
495 a CColor instance.</p>
496
497 <h4>CColor([r], [g], [b], [a])</h4>
498
499 <p>Constructs a <a href="#CColor">CColor</a> instance with the
500 specified Red, Green, Blue, and Alpha component values.
501 All arguments are optional.</p>
502
503 <h4><var>color</var>.R</h4>
504
505 <p>The red component, between 0 and 255.</p>
506
507 <h4><var>color</var>.G</h4>
508
509 <p>The green component, between 0 and 255.</p>
510
511 <h4><var>color</var>.B</h4>
512
513 <p>The blue component, between 0 and 255.</p>
514
515 <h4><var>color</var>.A</h4>
516
517 <p>The alpha component, between 0 and 255.
518 Not premultiplied.</p>
519
520 <p>Currently, the engine ignores the alpha component
521 of all CColor instances that Lua code can access:</p>
522
523 <ul>
524 <li><a href="#CFontColor.Colors"><var>fontColor</var>.Colors</a></li>
525 <li>UI.ButtonPanel.AutoCastBorderColorRGB</li>
526 <li>UI.CompletedBarColorRGB</li>
527 </ul>
528
529 <a name="CFontColor"></a>
530 <h3>CFontColor</h3>
531
532 <p>Each CFontColor instance represents a named set of colors for use
533 in <a href="#text_formatting">text formatting</a>.</p>
534
535 <p>In the following subsections, <var>fontColor</var> denotes
536 a CFontColor instance.</p>
537
538 <a name="CFontColor.Colors"></a>
539 <h4><var>fontColor</var>.Colors</h4>
540
541 <p>An array of <a href="#CColor">CColor</a> instances.
542 There are <a href="#MaxFontColors">MaxFontColors</a> elements in the array.
543 The engine ignores the alpha component of these CColor instances.</p>
544
545 <a name="CFontColor.Get"></a>
546 <h4>CFontColor:Get("name")</h4>
547
548 <p>Finds a font color by name.
549 Returns a <a href="#CFontColor">CFontColor</a> instance if found.
550 If no such font color has been defined, which indicates a bug,
551 then this function returns nil instead.</p>
552
553 <a name="CFontColor.New"></a>
554 <h4>CFontColor:New("name")</h4>
555
556 <p>Finds a font color by name, or allocates a new one.
557 Returns a <a href="#CFontColor">CFontColor</a> instance.
558 If it is a new one, then its <a href="#CFontColor.Colors">Colors</a>
559 array is all black, so you should set that before you use the
560 font color in <a href="#text_formatting">text formatting</a>.</p>
561
562 <a name="MaxFontColors"></a>
563 <h4>MaxFontColors</h4>
564
565 <p>This constant integer is the number of elements in the
566 <a href="#CFontColor.Colors">Colors</a> array in CFontColor
567 instances.</p>
568
569 <a name="CResourceInfo"></a>
570 <h3>CResourceInfo</h3>
571
572 <p>In the <a href="#UI.Resources">UI.Resources</a> table,
573 there is one CResourceInfo instance for each type of resource.
574 These objects control how the engine displays the resource costs of
575 a command. Each CResourceInfo instance has the following properties:</p>
576
577 <dl>
578 <dt><a name="CResourceInfo.G">G</a></dt>
579 <dd>The <a href="#CGraphic">CGraphic</a> instance
580 that contains the resource icon.</dd>
581 <dt><a name="CResourceInfo.IconFrame">IconFrame</a></dt>
582 <dd>The frame number of the resource icon within the graphic.
583 See <a href="unittype.html#frame_numbers">Frame numbers and flipping</a>.</dd>
584 <dt class="obsolete"><a name="CResourceInfo.IconX">IconX</a></dt>
585 <dd class="obsolete"><em>Obsolete since r8638 (2007-03-28):
586 The coordinates are hardcoded.</em>
587 The X coordinate of the resource icon on the screen,
588 for resources held by the player.</dd>
589 <dt class="obsolete"><a name="CResourceInfo.IconY">IconY</a></dt>
590 <dd class="obsolete"><em>Obsolete since r8638 (2007-03-28):
591 The coordinates are hardcoded.</em>
592 The Y coordinate of the resource icon on the screen,
593 for resources held by the player.</dd>
594 <dt class="obsolete"><a name="CResourceInfo.TextX">TextX</a></dt>
595 <dd class="obsolete"><em>Obsolete since r8638 (2007-03-28):
596 The coordinates are hardcoded.</em>
597 The X coordinate of the text that describes the amount
598 of resource held by the player.</dd>
599 <dt class="obsolete"><a name="CResourceInfo.TextY">TextY</a></dt>
600 <dd class="obsolete"><em>Obsolete since r8638 (2007-03-28):
601 The coordinates are hardcoded.</em>
602 The Y coordinate of the text that describes the amount
603 of resource held by the player.</dd>
604 </dl>
605
606 <p>These properties can be accessed with expressions like
607 <code>UI.Resources[EnergyCost].G</code>.</p>
608
609 <a name="CGraphic"></a>
610 <h3>CGraphic</h3>
611
612 <p>A CGraphic instance is a graphic image that can be loaded from a
613 file and then displayed on the screen.</p>
614
615 <p>In the following subsections, <var>graphic</var> denotes
616 a CGraphic instance.</p>
617
618 <a name="CGraphic.New"></a>
619 <h4>CGraphic:New("filename", [width], [height])</h4>
620
621 <p>Creates a CGraphic instance that refers to the specified image file,
622 unless one exists already.</p>
623
624 <dl>
625 <dt>"filename"</dt>
626 <dd>The name of the file from which
627 <a href="#CGraphic.Load">CGraphic::Load</a> will load the graphic.</dd>
628 <dt>width</dt>
629 <dd>The width of each frame in the graphic,
630 or 0 (default) to use the whole graphic as just one frame.</dd>
631 <dt>height</dt>
632 <dd>The height of each frame in the graphic,
633 or 0 (default) to use the whole graphic as just one frame.</dd>
634 <dt><i>RETURNS</i></dt>
635 <dd>A CGraphic instance that refers to the specified image file.
636 If one had already been created, then CGraphic::New returns that
637 and increments its reference count; otherwise, CGraphic::New
638 creates a new CGraphic instance.
639 In either case, <a href="#CGraphic.Free">CGraphic:Free</a>
640 will have to be called.</dd>
641 </dl>
642
643 <a name="CGraphic.Free"></a>
644 <h4>CGraphic:Free(graphic)</h4>
645
646 <p>Decrements the reference count of a CGraphic instance,
647 and frees it if the reference count becomes zero.</p>
648
649 <p>The reference counts of CGraphic instances are not currently
650 connected to Lua garbage collection. CGraphic:Free must be
651 called explicitly. If a CGraphic instance is used after it
652 has been freed, the engine will probably crash.</p>
653
654 <dl>
655 <dt>graphic</dt>
656 <dd>The CGraphic instance that the method should free.</dd>
657 <dt><i>RETURNS</i></dt>
658 <dd>Nothing.</dd>
659 </dl>
660
661 <a name="CGraphic.Load"></a>
662 <h4><var>graphic</var>:Load()</h4>
663
664 <p>Loads the graphic from the image file whose name was given
665 to <a href="#CGraphic.New">CGraphic:New</a>, unless it has
666 already been loaded.</p>
667
668 <dl>
669 <dt>graphic</dt>
670 <dd>The CGraphic instance that the method should load.</dd>
671 <dt><i>RETURNS</i></dt>
672 <dd>Nothing.</dd>
673 </dl>
674
675 <a name="CGraphic.Resize"></a>
676 <h4><var>graphic</var>:Resize(width, height)</h4>
677
678 <p>Resizes the graphic to the specified size.
679 Because <a href="#CGraphic.New">CGraphic:New</a> returns
680 the same CGraphic instance when given the same file name,
681 resizing can affect other uses of the same graphic.
682 To prevent such problems, you should use this method
683 only on graphics that are displayed in one place at a time
684 and are always resized before use.</p>
685
686 <dl>
687 <dt>graphic</dt>
688 <dd>The CGraphic instance that the method should resize.</dd>
689 <dt>width</dt>
690 <dd>The new width of the graphic, in pixels.</dd>
691 <dt>height</dt>
692 <dd>The new height of the graphic, in pixels.</dd>
693 <dt><i>RETURNS</i></dt>
694 <dd>Nothing.</dd>
695 </dl>
696
697 <hr>
698 All trademarks and copyrights on this page are owned by their respective owners.
699 <address>(c) 2002-2010 by <a href="http://boswars.org">
700 The Bos Wars Project</a></address></body></html>
701