<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head>
<!--
---- (c) Copyright 2002-2011 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>Stratagus Configuration Language Description: User Interface (UI)</title>
<meta name="Author" content="johns98@gmx.net">
<meta name="Keyword" content="scripts,tileset">
<meta name="Description" content="">
</head>
<body>
<pre width=80>
_________ __ __
/ _____// |_____________ _/ |______ ____ __ __ ______
\_____ \\ __\_ __ \__ \\ __\__ \ / ___\| | \/ ___/
/ \| | | | \// __ \| | / __ \_/ /_/ > | /\___ \
/_______ /|__| |__| (____ /__| (____ /\___ /|____//____ >
\/ \/ \//_____/ \/
______________________ ______________________
T H E W A R B E G I N S
Stratagus - A free fantasy real time strategy game engine
</pre>
<hr>
<h1>Stratagus Configuration Language Description: User Interface (UI)</h1>
<hr>
<a href="../index.html">Stratagus</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="#DefineButton">DefineButton</a>
<a href="#DefineButtonStyle">DefineButtonStyle</a>
<a href="#DefineCheckboxStyle">DefineCheckboxStyle</a>
<a href="#DefineCursor">DefineCursor</a>
<a href="#DefineMenu">DefineMenu</a>
<a href="#DefineMenuGraphics">DefineMenuGraphics</a>
<a href="#DefineMenuItem">DefineMenuItem</a>
<a href="#DefinePanelContents">DefinePanelContents</a>
<a href="#DefineUI">DefineUI</a>
<a href="#DefineViewports">DefineViewports</a>
<a href="#SetGameCursor">SetGameCursor</a>
<hr>
<h2>Intro - Introduction to UI functions and variables</h2>
Everything around the user interface.
<h2>Functions</h2>
<a name="DefineButton"></a>
<h3>DefineButton({tag1 = value1, tag2 value2, ...})</h3>
Define a button in the button panel show during the game. Possible tags:
<dl>
<dt>Pos = number</dt>
<dd>Position number.
<pre>
0 1 2
3 4 5
6 7 8
</pre>
</dd>
<dt>Level = number</dt>
<dd>Visible when in this button level (0 default, 9 cancel-only)
</dd>
<dt>Icon = "icon-name"</dt>
<dd>Name of the icon to display.
</dd>
<dt>Action = "action"</dt>
<dd>Action to perform when the button is clicked. Can be any of the following:
<dl>
<dt>"move"</dt>
<dd>The unit moves to location</dd>
<dt>"stop"</dt>
<dd>the unit stops. Orders queue is also erased. The unit wait for order but can react by itself.</dd>
<dt>"attack"</dt>
<dd>The unit attacks target. if target is a unit then it attacks only the unit.
If target is a position, it will move to location by attacking any opponent on the way.</dd>
<dt>"repair"</dt>
<dd>The unit will repair the target unit.</dd>
<dt>"harvest"</dt>
<dd>The unit will harvest the ressources.</dd>
<dt>"button"</dt>
<dd>FIXME. Need Value = number.</dd>
<dt>"build"</dt>
<dd>The unit will build the unit (building structure)</dd>
<dt>"train-unit"</dt>
<dd>The unit trains an unit. Generally use for building to create news units.
Need Value = "unit-name".</dd>
<dt>"patrol"</dt>
<dd>The unit patrol between target position and current position and attack any opponent
on the way.</dd>
<dt>"stand-ground"</dt>
<dd>The unit doesn't move. The unit stay at its location until it receives a new order.</dd>
<dt>"attack-ground"</dt>
<dd>The unit attack a location. Usefull for unit with spalsh damage.</dd>
<dt>"return-goods"</dt>
<dd>The unit with ressources return goods.</dd>
<dt>"cast-spell"</dt>
<dd>The unit cast a spell.
Need Value = "spell-name"</dd>
<dt>"research"</dt>
<dd>launch the research of an upgrade. Usefull to add technology.
Need Value = "upgrade-name"</dd>
<dt>"upgrade-to"</dt>
<dd>The unit will be trasform in an other unit (like polyporm spell).
Need Value = "Unit".
</dd>
<dt>"unload"</dt>
<dd>The unit unload unit inside of itself. Usefull for transporter or bunkers.</dd>
<dt>"cancel"</dt>
<dd>FIXME : difference between cancels.</dd>
<dt>"cancel-upgrade"</dt>
<dd>FIXME</dd>
<dt>"cancel-train-unit"</dt>
<dd>FIXME</dd>
<dt>"cancel-build"</dt>
<dd>FIXME</dd>
</dl>
</dd>
<dt>Value = arg</dt>
<dd>Optional value associated with the action.
</dd>
<dt>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>this button is forbidden. FIXME : ? to be removed. What is its usage ?</dd>
<dt>"check-upgrade"</dt>
<dd>This button can be clicked only when a specific upgrade is searched.
Need Allowarg = {"upgrade-name"}</dd>
<dt>"check-units-or"</dt>
<dd>this button is available if at least one of the unit are available.
Need AllowArg = {"unit-name1", "unit-name2"}</dd>
<dt>"check-units-and"</dt>
<dd>FIXME</dd>
<dt>"check-network"</dt>
<dd>Button is available only if network is available too.</dd>
<dt>"check-no-network"</dt>
<dd>Button is available only if network is not available.</dd>
<dt>"check-no-work"</dt>
<dd>FIXME</dd>
<dt>"check-no-research"</dt>
<dd>this button is available if the unit is not researching (upgrade-to or upgrade research).</dd>
<dt>"check-attack"</dt>
<dd>FIXME</dd>
<dt>"check-upgrade-to"</dt>
<dd>FIXME. No arg</dd>
<dt>"check-research"</dt>
<dd>FIXME</dd>
<dt>"check-single-research"</dt>
<dd>FIXME. No arg</dd>
</dl>
</dd>
<dt>AllowArg = {"arg1", ...}</dt>
<dd>Optional argument used by the allowed function.
</dd>
<dt>Key = "char"</dt>
<dd>Shortcut key for the button. (FE "c" for key 'c' or "\27" for Escape)
</dd>
<dt>Hint = "string"</dt>
<dd>Hint to be displayed for the button.
</dd>
<dt>ForUnit = {"unit-name1", ...} or {"*"} </dt>
<dd>List of units the button applies to, or {"*"} for all units.
</dd>
</dl>
<h4>Example</h4>
<pre>
DefineButton( { Pos = 8, Level = 0, Icon = "icon-build-advanced",
Action = "button", Value = 2,
Allowed = "check-units-or", AllowArg = {"unit-elven-lumber-mill", "unit-keep"},
Key = "v", 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>
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="DefineCheckboxStyle"></a>
<h3>DefineCheckboxStyle(style, {tag = value, ...})</h3>
Define a checkbox 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 = {},
Checked = {}, CheckedHover = {}, CheckedSelected = {}, CheckedClicked = {}, CheckedDisabled = {}</dt>
<dd>Set attributes for when the mouse is over the checkbox (Hover), the
checkbox is Selected, Clicked, Disabled, the Default setting, and for when the
checkbox is Checked. 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>
DefineCheckboxStyle("round", {
Size = {19, 19},
Font = "game",
TextNormalColor = "yellow",
TextReverseColor = "white",
TextAlign = "Left",
TextPos = {24, 4},
Default = {
File = "ui/buttons_1.png", Size = {300, 144}, Frame = 19,
},
Hover = {
TextNormalColor = "white",
},
Selected = {
Border = {
Color = {252, 252, 0}, Size = 1,
},
},
Disabled = {
File = "ui/buttons_1.png", Size = {300, 144}, Frame = 18,
},
Clicked = {
File = "ui/buttons_1.png", Size = {300, 144}, Frame = 20,
TextNormalColor = "white",
},
Checked = {
File = "ui/buttons_1.png", Size = {300, 144}, Frame = 21,
},
CheckedHover = {
TextNormalColor = "white",
},
CheckedSelected = {
Border = {
Color = {252, 252, 0}, Size = 1,
},
},
CheckedClicked = {
File = "ui/buttons_1.png", Size = {300, 144}, Frame = 22,
TextNormalColor = "white",
},
CheckedDisabled = {
File = "ui/buttons_1.png", Size = {300, 144}, Frame = 18,
},
})
</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>
<dt>Race = "race-name" or "any"</dt>
<dd>Race to use this cursor with or "any" to use with any race.
</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 Stratagus 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>
DefineCursor({
Name = "cursor-cross",
Race = "any",
File = "ui/cursors/small_green_cross.png",
HotSpot = {8, 8},
Size = {18, 18}})
</pre>
<a name="DefineMenu"></a>
<h3>DefineMenu("tag1", value1, ...)</h3>
FIXME: incomplete docu<br>
Possible tags:
<dl>
<dt>"geometry", {x, y, width, height}</dt>
<dd>Position and size of the menu.
</dd>
<dt>"name", "menu-name"</dt>
<dd>Name of this menu.</dd>
<dt>"panel", "panel-name" or "none"</dt>
<dd>Panel name (FIXME: how is it used?).</dd>
<dt>"default", number</dt>
<dd>Initial selected item number</dd>
<dt>"init", "function_name"</dt>
<dd>FIXME (function = "save-replay-init" or "scen-select-init" ? )</dd>
<dt>"exit", "function_name"</dt>
<dd>FIXME ("speed-options-exit" or "load-game-exit" ? )</dd>
<dt>"netaction", "menu-action"</dt>
<dd>FIXME: which are menu-action ?</dd>
<dl>
<dt>"terminate-net-connect"</dt>
<dd>FIXME</dd>
</dl>
</dl>
<h4>Example</h4>
<pre>
-- menu-sound-options
DefineMenu("name", "menu-sound-options", "geometry", {224, 64, 352, 352},
"panel", "panel5", "default", 23)
</pre>
<a name="DefineMenuGraphics"></a>
<h3>DefineMenuGraphics({{"tag", value, ...}, ...})</h3>
Define the menu graphics for each of the races.
FIXME : 1st graph is the 1st race ? ... Explain better
<dl>
<dt>"file", "filename"</dt>
<dd>Path to the file containing the menu graphics.</dd>
<dt>"size", {width, height}</dt>
<dd>Width and height of an image in the menu graphic.</dd>
</dl>
<h4>Example</h4>
<pre>
DefineMenuGraphics({
{"file", "ui/buttons_1.png", "size", {300, 144}},
{"file", "ui/buttons_2.png", "size", {300, 144}}})
</pre>
<a name="DefineMenuItem"></a>
<h3>DefineMenuItem("tag1", value1, ...)</h3>
Add an item to a menu. This could be any item, it depends
on the tags used.<br>
FIXME: incomplete docu<br>
<dl>
<dt>"pos", {x, y}</dt>
<dd>position of menuitem (FIXME abolute, or relative to something ?)</dd>
<dt>"menu", "menu-name"</dt>
<dd>Menu this item belongs to.</dd>
<dt>"transparent"</dt>
<dd>FIXME. No value</dd>
<dt>"flags", {"value",...}</dt>
<dd>FIXME
<dl>
<dt>"active"</dt>
<dd>FIXME</dd>
<dt>"clicked"</dt>
<dd>FIXME</dd>
<dt>"selected"</dt>
<dd>FIXME</dd>
<dt>"disabled"</dt>
<dd>FIXME</dd>
</dl>
</dd>
<dt>"font", "font-name"</dt>
<dd>Use "game", "small", "large", "small-title", "large-title",
"user1", "user2", "user3", "user4", "user5"</dd>
<dt>type, {arg_type}</dt>
<dd>type could be :</dd>
<dl>
<dt>"text", {values, ...}</dt>
<dd>The item is a text label.<br>
The value is a list of tags, allowed tags:
<dl>
<dt>"align", "left" or "right" or "center"</dt>
<dd>aligns text respectively at left, right or center.</dd>
<dt>"caption", "text"</dt>
<dd>The text.</dd>
<dt>"func", "function-name"</dt>
<dd>C handler. FIXME: when called?</dd>
<dt>"color-normal", "color-name"</dt>
<dd>FIXME.</dd>
<dt>"color-reverse", "color-name"</dt>
<dd>FIXME.</dd>
</dl>
</dd>
For example:
<pre>
"text", {"caption", "Connecting to server",
"align", "center"}
</pre>
<dt>"button" = {values, ...}</dt>
<dd>The item is a button.<br>
The value is a list of tags like:
<dl>
<dt>"caption", "text"</dt>
<dd>The text.</dd>
<dt>"color-normal", "color-name"</dt>
<dd>FIXME.</dd>
<dt>"color-reverse", "color-name"</dt>
<dd>FIXME.</dd>
<dt>"hotkey", "key"</dt>
<dd>A string like "f8". FIXME</dd>
<dt>"func", "function-name" or Lua function</dt>
<dd>Called when a button is clicked</dd>
<dt>"style", style-name</dt>
<dd>Complete list of possible styles-name:
FIXME (not all for buttons)
<dl>
<dt>"main"</dt>
<dd>FIXME</dd>
<dt>"network"</dt>
<dd>FIXME</dd>
<dt>"gm-half"</dt>
<dd>FIXME</dd>
<dt>"132"</dt>
<dd>FIXME</dd>
<dt>"gm-full"</dt>
<dd>FIXME</dd>
<dt>"gem-round"</dt>
<dd>FIXME</dd>
<dt>"gem-square"</dt>
<dd>FIXME</dd>
<dt>"up-arrow"</dt>
<dd>FIXME</dd>
<dt>"down-arrow"</dt>
<dd>FIXME</dd>
<dt>"left-arrow"</dt>
<dd>FIXME</dd>
<dt>"right-arrow"</dt>
<dd>FIXME</dd>
<dt>"s-knob"</dt>
<dd>FIXME</dd>
<dt>"s-vcont"</dt>
<dd>FIXME</dd>
<dt>"s-hcont"</dt>
<dd>FIXME</dd>
<dt>"pulldown"</dt>
<dd>FIXME</dd>
<dt>"vthin"</dt>
<dd>FIXME</dd>
<dt>"folder"</dt>
<dd>FIXME</dd>
<dt>"sc-gem-round"</dt>
<dd>FIXME</dd>
<dt>"sc-gem-square"</dt>
<dd>FIXME</dd>
<dt>"sc-up-arrow"</dt>
<dd>FIXME</dd>
<dt>"sc-down-arrow"</dt>
<dd>FIXME</dd>
<dt>"sc-left-arrow"</dt>
<dd>FIXME</dd>
<dt>"sc-right-arrow"</dt>
<dd>FIXME</dd>
<dt>"sc-s-knob"</dt>
<dd>FIXME</dd>
<dt>"sc-s-vcont"</dt>
<dd>FIXME</dd>
<dt>"sc-s-hcont"</dt>
<dd>FIXME</dd>
<dt>"sc-pulldown"</dt>
<dd>FIXME</dd>
<dt>"sc-button-left"</dt>
<dd>FIXME</dd>
<dt>"sc-button"</dt>
<dd>FIXME</dd>
<dt>"sc-button-right"</dt>
<dd>FIXME</dd>
</dl>
FIXME: describe them
</dd>
</dl>
</dd>
Example.
<pre>
"button", {"size", {224, 27},
"caption", "~!Surrender",
"hotkey", "s",
"func", "surrender-confirm-menu"
"style", "gm-full"}
</pre>
<dt>"pulldown"</dt>
<dd>The item is a pulldown menu.
<dl>
<dt>"size" = (width, height)</dt>
<dd>Dimensions.</dd>
<dt>"options", {"string1", "string2", ...}</dt>
<dd>A list of strings to select from.</dd>
<dt>"color-normal", "color-name"</dt>
<dd>FIXME.</dd>
<dt>"color-reverse", "color-name"</dt>
<dd>FIXME.</dd>
<dt>"func", function-name</dt>
<dd>C handler. FIXME: when called?</dd>
<dt>"state", "passive"</dt>
<dd>FIXME</dd>
<dt>"default", number</dt>
<dd>An integer for the default selection id, starting with 0.</dd>
<dt>"current", number</dt>
<dd>An integer for the current selection id, starting with 0.</dd>
<dt>"style" = style-name</dt>
<dd>see above. FIXME which are available ?</dd>
</dl>
</dd>
Example:
<pre>
"pulldown", {"size", {152, 20},
"style", "pulldown",
"func", "null",
"options", {"Forest", "Winter", "Wasteland", "Orc Swamp"},
"default, 0, -- "Forest"
"current", 0} -- "Forest"
</pre>
<dt>"listbox"</dt>
<dd>The item is a list box.<br>
Allowed tags:
<dl>
<dt>"size" = (width, height)</dt>
<dd>Dimensions.</dd>
<dt>"func", function-name</dt>
<dd>C handler. FIXME: when called?</dd>
<dt>"handler", function-name</dt>
<dd>C handler. FIXME: when is it called?</dd>
<dt>"retopt", function-name</dt>
<dd>C handler to retrieve the list of options, I guess. FIXME</dd>
<dt>"startline", number</dt>
<dd>For scrolling, I guess. Probably only used in savegames. FIXME</dd>
<dt>"nlines", number</dt>
<dd>Number of lines.</dd>
<dt>"default", number</dt>
<dd>An integer for the default selection id, starting with 0.</dd>
<dt>"current", number</dt>
<dd>An integer for the current selection id, starting with 0.</dd>
<dt>"style" = style-name</dt>
<dd>see above. FIXME which are available ?</dd>
<dt>"color-normal", "color-name"</dt>
<dd>FIXME.</dd>
<dt>"color-reverse", "color-name"</dt>
<dd>FIXME.</dd>
</dl>
</dd>
Example:
<pre>
"listbox", {"size", {288, 108},
"style", "pulldown",
"func", "scen-select-lb-action",
"retopt", "scen-select-lb-retrieve",
"handler", "scen-select-ok",
"nlines", 6}
</pre>
<dt>"vslider" or "hslider", {values}</dt>
<dd>The item is a vertical (or horizontal) slider.<br>
Allowed tags: size default current style (see above) and:
<dl>
<dt>"size" = (width, height)</dt>
<dd>Dimensions.</dd>
<dt>"func", function-name</dt>
<dd>C handler. FIXME: when called?</dd>
<dt>"handler", function-name</dt>
<dd>C handler. FIXME: when is it called?</dd>
<dt>"flags", "up" or "down" or "left" or "right" or "knob" or "cont"</dt>
<dd>FIXME: never seen this used.</dd>
<dt>"default", number</dt>
<dd>An integer for the default selection id, starting with 0.</dd>
<dt>"current", number</dt>
<dd>An integer for the current selection id, starting with 0.</dd>
<dt>"style" = style-name</dt>
<dd>see above. FIXME which are available ?</dd>
</dl>
Examples:
<pre>
"vslider", {"size", {18, 108},
"func", "editor-main-load-vs-action",
"handler", "editor-main-load-ok"}
</pre>
<pre>
"hslider", {"size", {198, 18},
"func", "master-volume-hs-action",
"handler", "scen-select-ok"}
</pre>
</dd>
<dt>"drawfunc", function-name</dt>
<dd>The item is drawn from a C function.<br>
Example:
<pre>
DefineMenuItem("pos", {0, 0}, "font", "game", "init", "game-setup-init",
"drawfunc", "game-draw-func",
"menu" "menu-custom-game")
</pre>
FIXME.
</dd>
<dt>"input"</dt>
<dd>The item is a text input field.<br>
Allowed tags: size func style color-normal color-reverse (see above)
and:
<dl>
<dt>"size" = (width, height)</dt>
<dd>Dimensions.</dd>
<dt>"func", function-name</dt>
<dd>C handler, seems to be called when a key is pressed
and just checks whether it is RETURN.
</dd>
<dt>"style" = style-name</dt>
<dd>see above. FIXME which are available ?</dd>
<dt>"color-normal", "color-name"</dt>
<dd>FIXME.</dd>
<dt>"color-reverse", "color-name"</dt>
<dd>FIXME.</dd>
<dt>"maxch", number</dt>
<dd>Maximal number of characters. FIXME: never seen this used.</dd>
</dl>
</dd>
Example:
<pre>
"input", {"size", {212, 20},
"func", "enter-master-action",
"style", "pulldown"}
</pre>
<dt>"gem"</dt>
<dd>The item is a gem.<br>
Allowed tags: size func style text color-normal color-reverse (see
above) and:
<dl>
<dt>"size" = (width, height)</dt>
<dd>Dimensions.</dd>
<dt>"func", function-name</dt>
<dd>C handler. FIXME: when called?</dd>
<dt>"state", "checked" or "unchecked" or "passive" or "invisible"</dt>
<dd>FIXME.</dd>
<dt>"style" = style-name</dt>
<dd>see above. FIXME which are available ?</dd>
<dt>"text", "text"</dt>
<dd>The text.</dd>
<dt>"color-normal", "color-name"</dt>
<dd>FIXME.</dd>
<dt>"color-reverse", "color-name"</dt>
<dd>FIXME.</dd>
<dt>"maxch", number</dt>
<dd>Maximal number of characters. FIXME: never seen this used.</dd>
</dl>
</dd>
Example:
<pre>
"gem", {"size", {18, 18},
"text", "640 x 480",
"state", "unchecked",
"func", "global-options-resolution-gem",
"style", "gem-round"}
</pre>
</dl>
</dl>
<h4>Example</h4>
<pre>
DefineMenuItem("pos", {16, 288 - 40}, "font", "large",
"button", {"size", {224, 27},
"caption", "Return to Game (~<Esc~>)",
"hotkey", "esc",
"func", "game-menu-return",
"style", "gm-full"},
"menu", "menu-game")
</pre>
<a name="DefinePanelContents"></a>
<h3>DefinePanelContents({flag = value}, ...)</h3>
Define panel content when an unit is selected.
<dl>
<dt>Ident = "name"</dt>
<dd>identifier of the panel.</dd>
<dt>Pos = {x, y}<dt>
<dd>position of the panel. The other coordonate are relative to this point.</dd>
<dt>DefaultFont = "font-name"<dt>
<dd>Default font used in content if not redefined.</dd>
<dt>Condition = {flag = value}</dt>
<dd>condition to show the panel.
<dl>
<dt>ShowOnlySelected = Boolean</dt>
<dd>if true, show only if unit is selected (not just pointed).</dd>
<dt>HideNeutral = Boolean</dt>
<dd>if true, hide for neutral units.</dd>
<dt>HideAllied = Boolean</dt>
<dd>if true, hide for allied units.</dd>
<dt>ShowOpponent = Boolean</dt>
<dd>if true, show for opponent units.</dd>
<dt>Variable = "only", "false", "true"<dt>
<dd>For variables defined by DefineVariables(), show info if unit correpond with the criteria<dd>
<dt>Flag = "only", "false", "true"<dt>
<dd>For flags defined by DefineBoolFlags(), show info if unit correpond with the criteria<dd>
</dl> </dd>
<dt>Contents = {flag = value}</dt>
<dd>The info to show, and the method associated.
<dl>
<dt>Pos = {x, y}</dt>
<dd>Coordinate to show element. (relatif to Panel' coordinates)</dd>
<dt>Condition = {flag = value}</dt>
<dd>Extra condition for content itself. Identic as Panel's condition</dd>
<dt>More = {"method-name", ExtraData}</dt>
<dd>Tell the method to show informations.
<dl>
<dt>"Text", "texttodisplay" or {flag = value}</dt>
<dd>Show simple text "texttodisplay" and after one optional variable.
<dl>
<dt>Text = StringDesc</dt>
<dd>text to display (See StringDesc in Trigger).</dd>
<dt>Font = "font-name"</dt>
<dd>font to use.</dd>
<dt>Centered = boolean</dt>
<dd>if true then text is centered on the position.</dd>
<dt>Variable = "variable-name"</dt>
<dd>Variable name to show. See DefineVariable() for more details.</dd>
<dt>Component = "Name" or "Value" or "Max" or "Increase" or "Diff" or "Percent"</dt>
<dd>component of value to show. Diff represent Max - value and Percent represent 100 * Value / Max.</dd>
<dt>ShowName = boolean</dt>
<dd>if true show the name of the unit and no variable information.</dd>
<dt>Stat = boolean</dt>
<dd>if true and value != Original value, then show original value + diff else show value.
Original value is default value with no upgrade.
</dd>
</dl></dd>
<dt>"FormatedText", {flag = value, ...}</dt>
<dd>Show text with a given format.
<dl>
<dt>Format = "texttodisplay"</dt>
<dd>format of the text. Must have 1 %d (for number)or %s (for string). Use ~< ~> for reverse mode.</dd>
<dt>Font = "font-name"</dt>
<dd>font to use.</dd>
<dt>Variable = "variable-name"</dt>
<dd>Variable name to show. See DefineVariable() for more details.</dd>
<dt>Component = "Name" or "Value" or "Max" or "Increase" or "Diff" or "Percent"</dt>
<dd>component of value to show. Diff represent Max - value and Percent represent 100 * Value / Max.</dd>
<dt>Centered = boolean</dt>
<dd>if true then text is centered on the position.</dd>
</dl></dd>
<dt>"FormatedText2", {flag = value, ...}</dt>
<dd>Similar of FormatedText but with 2 variables.
<dl>
<dt>Format = "texttodisplay"</dt>
<dd>format of the text. Must have 2 %d (for number)or %s (for string). Use ~< ~> for reverse mode.</dd>
<dt>Font = "font-name"</dt>
<dd>font to use.</dd>
<dt>Variable1 = "variable-name"</dt>
<dd>1st Variable name to show. See DefineVariable() for more details.</dd>
<dt>Variable2 = "variable-name"</dt>
<dd>2nd Variable name to show. See DefineVariable() for more details.</dd>
<dt>Variable = "variable-name"</dt>
<dd>Variable name to show(Assume var1 == var2). See DefineVariable() for more details.</dd>
<dt>Component1 = "Name" or "Value" or "Max" or "Increase" or "Diff" or "Percent"</dt>
<dd>component of the 1st value to show. Diff represent Max - value and Percent represent 100 * Value / Max.</dd>
<dt>Component2 = "Name" or "Value" or "Max" or "Increase" or "Diff" or "Percent"</dt>
<dd>component of 2nd value to show. Diff represent Max - value and Percent represent 100 * Value / Max.</dd>
<dt>Component = "Name" or "Value" or "Max" or "Increase" or "Diff" or "Percent"</dt>
<dd>Assume that component1 == component2.</dd>
<dt>Centered = boolean</dt>
<dd>if true then text is centered on the position.</dd>
</dl></dd>
<dt>"Icon", {flag = value, ...}</dt>
<dd>Draw the icon of a specified unit.
<dl>
<dt>Unit = "ItSelf" or "Inside" or "Container" or "Worker" or "Goal"</dt>
<dd>which unit to draw : itself or first unit inside or its container
or the unit which is building it or the goal objective.</dd>
</dl></dd>
<dt>"LifeBar", {flag = value, ...}</dt>
<dd>Draw a bar which represent the variable. Change color depend of the percent.
<dl>
<dt>Variable = "variable-name"</dt>
<dd>Variable name to show. See DefineVariable() for more details.</dd>
<dt>Height = value</dt>
<dd>Height of the bar.</dd>
<dt>Width = value</dt>
<dd>width of the bar.</dd>
</dl></dd>
<dt>"CompleteBar", {flag = value, ...}</dt>
<dd>Draw a bar which represent the variable.
<dl>
<dt>Variable = "variable-name"</dt>
<dd>Variable name to show. See DefineVariable() for more details.</dd>
<dt>Height = value</dt>
<dd>Height of the bar.</dd>
<dt>Width = value</dt>
<dd>width of the bar.</dd>
<dt>Border = boolean</dt>
<dd>if true then add border for the bar.</dd>
</dl></dd>
</dl></dd>
</dd></dl>
</dl>
<a name="DefineUI"></a>
<h3>DefineUI("race-name", screen-width, screen-height, tag1, value1, tag2, value2, ...)</h3>
<dl>
<dt>"race-name"</dt>
<dd>FIXME</dd>
<dt>screen-width, screen-height</dt>
<dd>FIXME</dd>
</dl>
All of those tags should be given:
<dl>
<dt>"normal-font-color", "color-name"</dt>
<dd>FIXME</dd>
<dt>"reverse-font-color", "color-name"</dt>
<dd>FIXME</dd>
<dt>"filler", {tag, value, ...}</dt>
<dd>FIXME:
<dl>
<dt>"file", "path"</dt>
<dd>FIXME</dd>
<dt>"pos", {x, y}</dt>
<dd>FIXME</dd>
</dl>
</dd>
<dt>"resource-line", {"file-name", x, y}</dt>
<dd>
FIXME
<dl>
<dt>"file-name"</dt>
<dd>FIXME</dd>
<dt>x, y</dt>
<dd>FIXME</dd>
</dl>
</dd>
<dt>"resources", {"ressource-name", {tag, value, ...}, ...}</dt>
<dd>
<dl>
<dt>"ressource-name" or "food" or "score"</dt>
<dd>FIXME</dd>
</dl>
FIXME
<dl>
<dt>"file", "file-name"</dt>
<dd>FIXME</dd>
<dt>"frame", number</dt>
<dd>FIXME</dd>
<dt>"pos", {x, y}</dt>
<dd>FIXME</dd>
<dt>"size", {width, height}</dt>
<dd>FIXME</dd>
<dt>"text-pos", {x, y}</dt>
<dd>FIXME</dd>
</dl>
</dd>
<dt>"info-panel", {tag, value, ...}</dt>
<dd>
<dl>
<dt>"panel", {tag, value}</dt>
<dd>FIXME
<dl>
<dt>"file", "file-name"</dt>
<dd>FIXME</dd>
<dt>"pos", {x, y}</dt>
<dd>FIXME</dd>
<dt>"size", {width, height}</dt>
<dd>FIXME</dd>
</dl>
</dd>
<dt>"panels", "panel-ident" or {"panel-ident1", ...}</dt>
<dd>Panel ident to show when unit is selected. (see DefinePanels() for more details)</dd>
<dt>"selected", {tag, value}</dt>
<dd>FIXME
<dl>
<dt>"single", {tag, value}</dt>
<dd>FIXME
<dl>
<dt>"text", {tag, value}</dt>
<dd>FIXME</dd>
<dt>"icon", {tag, value}</dt>
<dd>FIXME</dd>
</dl>
</dd>
<dt>"multiple", {tag, value}</dt>
<dd>FIXME
<dl>
<dt>"icons", {{tag, value}, ...}</dt>
<dd>FIXME, see above (icon)</dd>
<dt>"max-text", {tag, value}</dt>
<dd>FIXME, see above (text)</dd>
</dl>
</dd>
</dl>
</dd>
<dt>"training", {tag, value}</dt>
<dd>FIXME
<dl>
<dt>"single", {tag, value}</dt>
<dd>FIXME
<dl>
<dt>"icon", {tag, value}</dt>
<dd>FIXME</dd>
</dl>
</dd>
<dt>"multiple", {tag, value}</dt>
<dd>FIXME
<dl>
<dt>"text", {tag, value}</dt>
<dd>FIXME</dd>
<dt>"icons", {{tag, value}, ...}</dt>
<dd>FIXME, see above (icon)</dd>
</dl>
</dd>
</dl>
</dd>
<dt>"upgrading", {tag, value}</dt>
<dd>FIXME
<dl>
<dt>"icon", {tag, value}</dt>
<dd>FIXME</dd>
</dl>
</dd>
<dt>"researching", {tag, value}</dt>
<dd>FIXME
<dl>
<dt>"icon", {tag, value}</dt>
<dd>FIXME</dd>
</dl>
</dd>
<dt>"transporting", {tag, value}</dt>
<dd>FIXME
<dl>
<dt>"icons", {{tag, value}, ...}</dt>
<dd>FIXME, see above (icon)</dd>
</dl>
</dd>
<dt>"completed-bar", {tag, value}</dt>
<dd>FIXME
<dl>
<dt>"color", {r, g, b}</dt>
<dd>FIXME</dd>
<dt>"has-shadow"</dt>
<dd>FIXME</dd>
</dl>
</dd>
</dl>
</dd>
<dt>"button-panel", {tag, value, ...}</dt>
<dd>
<dl>
<dt>"panel", {tag, value, ...}</dt>
<dd>FIXME
<dl>
<dt>"file", "filename"</dt>
<dd>FIXME</dd>
<dt>"pos", {x, y}</dt>
<dd>FIXME</dd>
</dl>
</dd>
<dt>"icon", {tag, value, ...}</dt>
<dd>FIXME
<dl>
<dt>FIXME</dt>
<dd>FIXME</dd>
</dl>
</dd>
</dl>
</dd>
<dt>"pie-menu", {tag, value, ...}</dt>
<dd>
<dl>
<dt>"radius", radius</dt>
<dd>The radius in pixels of the pie menu.</dd>
<dt>"file", "filename"</dt>
<dd>The image file for the background of the pie menu.</dd>
<dt>"mouse-button", "buttonname"</dt>
<dd>Which mouse button pops up the pie menu. Can be "right", "middle" or "left".
</dd>
</dl>
</dd>
<dt>"map-area", {"pos", {x, y}, size, {w, h}}</dt>
<dd>FIXME</dd>
<dt>"menu-panel", {tag, value}</dt>
<dd>FIXME
<dl>
<dt>"panel", {tag, value, ...}</dt>
<dd>FIXME
<dl>
<dt>"file", "filename"</dt>
<dd>FIXME</dd>
<dt>"pos", {x, y}</dt>
<dd>FIXME</dd>
</dl>
</dd>
<dt>type-menu-button, {tag, value, ...}</dt>
<dd>type-menu-button is one of the following :
<dl>
<dt>"menu-button"</dt>
<dd>FIXME</dd>
<dt>"network-menu-button"</dt>
<dd>FIXME</dd>
<dt>"network-diplomacy-button"</dt>
<dd>FIXME</dd>
</dl>
<br>
And tag and value :
<dl>
<dt>"caption" , "text"</dt>
<dd>FIXME</dd>
<dt>"pos", {x, y}</dt>
<dd>FIXME</dd>
<dt>"style", "style-name"</dt>
<dd>FIXME, see above</dd>
</dl>
</dd>
</dl>
</dd>
<dt>"minimap", {tag, value}</dt>
<dd>
There is a minimap panel an the minimap on it. The panel graphic has
certain palette restrictions (FIXME: exactly? probably the same as the
tileset?).
<dl>
<dt>"file", filename</dt>
<dd>FIXME</dd>
<dt>"panel-pos", {x, y}</dt>
<dd>FIXME</dd>
<dt>"pos", {x, y}</dt>
<dd>Pos is the absoloute position of the minimap on the screen
(the upper left corner of it).
</dd>
<dt>"size", {w, h}</dt>
<dd>FIXME</dd>
<dt>"transparent"</dt>
<dd>If you give "transparent", the panel
graphic will be displayed on unexplored terrain, black otherwise.
</dd>
</dl>
</dd>
<dt>"status-line", {tag, value}</dt>
<dd>FIXME
<dl>
<dt>"file", "file-name"</dt>
<dd>FIXME</dd>
<dt>"pos", {x, y}</dt>
<dd>FIXME</dd>
<dt>"text-pos", {x, y}</dt>
<dd>FIXME</dd>
<dt>"font", "font-name"</dt>
<dd>FIXME</dd>
</dl>
</dd>
<dt>"cursors", {tag, name}</dt>
<dd>FIXME
<dl>
<dt>"point", "name"</dt>
<dd>FIXME</dd>
<dt>"glass", "name"</dt>
<dd>FIXME</dd>
<dt>"cross", "name"</dt>
<dd>FIXME</dd>
<dt>"yellow", "name"</dt>
<dd>FIXME</dd>
<dt>"green", "name"</dt>
<dd>FIXME</dd>
<dt>"red", "name"</dt>
<dd>FIXME</dd>
<dt>"scroll", "name"</dt>
<dd>FIXME</dd>
<dt>"arrow-e" or "arrow-ne" or "arrow-n" or "arrow-nw" or "arrow-w" or "arrow-sw" or "arrow-s" or "arrow-se", "name"</dt>
<dd>FIXME</dd>
</dl>
</dd>
<dt>"menu-panels", {"panel-name1", "file1", ...}</dt>
<dd>FIXME: this really needs docu or change, if you dig out the
requirement of the pictures, write them down here. Example:
</dd>
<dt>"victory-background", "file-name"</dt>
<dd>Background image for the victory screen. The image will be scaled.</dd>
<dt>"defeat-background", "file-name"</dt>
<dd>Background image for the victory screen. The image will be scaled.</dd>
</dl>
<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>
-- 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>
-- Set the game cursor to 'cursor-point'.
SetGameCursor("cursor-point")
</pre>
<hr>
(C) Copyright 2002-2011 by The <a href="https://launchpad.net/stratagus">Stratagus</a> Project
under the <a href="../gpl.html">GNU General Public License</a>.<br>
All trademarks and copyrights on this page are owned by their respective owners.<br>
</body>
</html>
distrib
>
Mandriva
>
2010.1
>
x86_64
>
media
>
contrib-backports
>
by-pkgid
>
fdcb562c48bbc70273d9b80c58e137e3
>
files
>
60
