<!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>
distrib
>
Mageia
>
6
>
x86_64
>
media
>
core-updates
>
by-pkgid
>
6ef0fdc2c18d666ec7b59c27c05c5d78
>
files
>
32
