From 5b98be7ec5a7ba1b5654273f8e1162a4339f8bf8 Mon Sep 17 00:00:00 2001
From: martinxyz <>
Date: Mon, 1 Sep 2003 19:02:07 +0000
Subject: [PATCH] updated ui docu
---
doc/scripts/ccl.html | 66 +---
doc/scripts/ui.html | 773 ++++++++++++++++++++++++++++++++-----------
2 files changed, 598 insertions(+), 241 deletions(-)
diff --git a/doc/scripts/ccl.html b/doc/scripts/ccl.html
index 6c38c75a1..302f1956c 100644
--- a/doc/scripts/ccl.html
+++ b/doc/scripts/ccl.html
@@ -52,62 +52,20 @@ the different games a configuration language is needed.<br>
I have chosen scheme because it is easy to parse and produces easy to read
config files.<p>
-<h2>Help</h2>
-
-Like everything in this project, I also need help here. Nothing is fixed.
-The syntax of all these functions could be changed or rewritten if
-needed. These are only my suggestions to have something to start with.
-
-<h2>Index</h2>
-
-<a href="ccl-index.html">Here is an index of all the ccl functions.</a>
-
<h2>Content</h2>
-<h3>Artificial Intelligence (AI)</h3>
-
-<a href="ai.html"> Artificial Intelligence (AI) </a>
-
-<h3>General config</h3>
-
-<a href="config.html"> Config </a>
-
-<h3>Game</h3>
-
-<a href="game.html"> Game </a>
-
-<h3>Icon</h3>
-
-<a href="icon.html"> Icon </a>
-
-<h3>Research and Upgrades</h3>
-
-<a href="research.html"> Research and Upgrades </a>
-
-<h3>Sound</h3>
-
-<a href="sound.html"> Sound </a>
-
-<h3>Tileset</h3>
-
-<a href="tileset.html"> Tileset </a>
-
-<h3>Triggers</h3>
-
-<a href="triggers.html"> Triggers </a>
-
-<h3>User Interface (UI)</h3>
-
-<a href="ui.html"> User Interface (UI) </a>
-
-<h3>UnitType</h3>
-
-<a href="unittype.html"> UnitType </a>
-
-<h3>FIXME:</h3>
-
-Sorry I haven't had more time to complete this section. You are welcome
-to finish it or if you need some information just email your request.
+<a href="ai.html">Artificial Intelligence (AI)</a> <br>
+<a href="config.html">Config</a> <br>
+<a href="game.html">Game</a> <br>
+<a href="icon.html">Icon</a> <br>
+<a href="research.html">Research and Upgrades</a> <br>
+<a href="sound.html">Sound</a> <br>
+<a href="tileset.html">Tileset</a> <br>
+<a href="triggers.html">Triggers</a> <br>
+<a href="ui.html">User Interface (UI)</a> <br>
+<a href="unittype.html">UnitType</a> <br>
+<p>
+<a href="ccl-index.html">Index</a> of all the ccl functions.
<hr>
Last changed: $Id$<br>
diff --git a/doc/scripts/ui.html b/doc/scripts/ui.html
index e2fa14ca6..985f71ee5 100644
--- a/doc/scripts/ui.html
+++ b/doc/scripts/ui.html
@@ -62,29 +62,27 @@
<hr>
<h2>Intro - Introduction to UI functions and variables</h2>
-Everything around the UI.
+Everything around the user interface.
<h2>Functions</h2>
<a name="define-button"></a>
-<h3>define-button</h3>
+<h3>(define-button 'tag1 value1 'tag2 value2 ...)</h3>
-<h4>Description</h4>
-
-Define a button.
-
-<h4>Syntax</h4>
-
-<code>(define-button 'pos pos 'level level 'icon icon<br>
- 'action action ['value value]<br>
- ['allowed allowed 'allow-arg allowarg]<br>
- 'key key 'hint hint<br>
- 'for-unit '(forunit))</code>
+Define a button in the button panel show during the game. Possible tags:
<dl>
+<dt>forunit</dt>
+<dd>List of units the button applies to, or '(*) for all units.
+</dd>
<dt>pos</dt>
-<dd>Position number.
+<dd>Position number.
+<pre>
+0 1 2
+3 4 5
+6 7 8
+</pre>
</dd>
<dt>level</dt>
-<dd>Level number.
+<dd>Visible when in this button level (0 default, 9 cancel-only)
</dd>
<dt>icon</dt>
<dd>Name of the icon to display.
@@ -113,39 +111,22 @@ check-upgrade-to, check-research, check-single-research.
<dt>hint</dt>
<dd>Hint to be displayed for the button.
</dd>
-<dt>forunit</dt>
-<dd>List of units the button applies to.
-</dd>
</dl>
<h4>Example</h4>
-
<pre>
- (define-button 'pos 1 'level 0 'icon 'icon-move-peasant
- 'action 'move
- 'key "m" 'hint "~MOVE"
- 'for-unit '(unit-footman unit-knight))
+ (define-button 'pos 9 'level 0 'icon 'icon-exorcism
+ 'action 'cast-spell 'value 'spell-exorcism
+ 'allowed 'check-upgrade 'allow-arg '(upgrade-exorcism)
+ 'key "e" 'hint "~!EXORCISM"
+ 'for-unit '(unit-paladin unit-knight-rider unit-man-of-light))
</pre>
-<p>Defines the move button for the footman and knight.
-
-<h4>Used</h4>
-
-<a href="../../data/ccl/human/buttons.ccl"> $LIBARYPATH/ccl/human/buttons.ccl </a> ,
-<a href="../../data/ccl/orc/buttons.ccl"> $LIBARYPATH/ccl/orc/buttons.ccl </a>
-
<a name="define-cursor"></a>
-<h3>define-cursor</h3>
-
-<h4>Description</h4>
+<h3>(define-cursor 'ident 'race 'tag1 value1 'tag2 value2 ...)</h3>
Define a cursor.
-<h4>Syntax</h4>
-
-<code>(define-cursor ident race 'image image<br>
- 'hot-spot '(x y) 'size '(width height) ['rate rate])</code>
-
<dl>
<dt>ident</dt>
<dd>Unique identifier of the cursor, used to reference it in config files and
@@ -154,16 +135,19 @@ during startup.
<dt>race</dt>
<dd>Race to use this cursor with or "any" to use with any race.
</dd>
+</dl>
+Possible tags:
+<dl>
<dt>image</dt>
<dd>Path to the image graphic.
</dd>
<dt>hot-spot</dt>
-<dd>Hot spot of the cursor in pixels. Relative to the sprite origin (0,0). The
+<dd>Hot spot of the cursor in pixels, in the form '(x y). 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</dt>
-<dd>Size of the cursor in pixels.
+<dd>Size of the cursor in pixels, in the form '(width height).
</dd>
<dt>rate</dt>
<dd>Rate of changing the frames if using an animated cursor. The "rate" tells
@@ -172,32 +156,18 @@ the engine how many milliseconds to hold each frame of the animation.
</dl>
<h4>Example</h4>
-
<pre>
+ ;; defines the cross cursor for any race
(define-cursor 'cursor-cross 'any
'image "ui/cursors/small green cross.png"
'hot-spot '(8 8) 'size '(18 18))
</pre>
-<p>Defines the cross cursor for any race.
-
-<h4>Used</h4>
-
-<a href="../../data/ccl/ui.ccl"> $LIBARYPATH/ccl/ui.ccl </a> ,
-<a href="../../data/ccl/human/ui.ccl"> $LIBARYPATH/ccl/human/ui.ccl </a> ,
-<a href="../../data/ccl/orc/ui.ccl"> $LIBARYPATH/ccl/orc/ui.ccl </a>
-
<a name="define-font"></a>
-<h3>define-font</h3>
-
-<h4>Description</h4>
+<h3>(define-font type file sizex sizey)</h3>
Define a font.
-<h4>Syntax</h4>
-
-<code>(define-font type file size)</code>
-
<dl>
<dt>type</dt>
<dd>Type of font. Supported types are: 'game, 'small, 'large, 'small-title,
@@ -212,177 +182,623 @@ and 'large-title.
</dl>
<h4>Example</h4>
-
<pre>
+ ;; define the game font
(define-font 'game "graphics/ui/fonts/game.png" 13 14)
</pre>
-<p>Define the game font.
+<a name="define-font-color"></a>
+<h3>(define-font-color color array)</h3>
-<h4>Used</h4>
-
-<a href="../../data/ccl/fonts.ccl"> $LIBARYPATH/ccl/fonts.ccl </a>
-
-<a name="define-font-colors"></a>
-<h3>define-font-colors</h3>
-
-<h4>Description</h4>
-
-.
-
-<h4>Syntax</h4>
-
-<code>(define-font-colors)</code>
+Define the font colors.<br>
+FIXME: write something here if you understand it... where are those colors used?
+What's the relation with the palette?
<dl>
-<dt></dt>
-<dd>.
+<dt>color</dt>
+<dd>Name of the color.
</dd>
+<dt>array</dt>
+<dd>Name of the color.
+Array of 7 rgb colors #( r1 g1 b1 r2 g2 b2 ...)<br>
+The colors are:
+<table>
+<tr><td>#0 </td><td>is background color</td></tr>
+<tr><td>#1 </td><td>is the light font color</td></tr>
+<tr><td>#2 </td><td>is the middle (main) font color</td></tr>
+<tr><td>#3 </td><td>is the dark font color</td></tr>
+<tr><td>#4 </td><td>is the font/shadow antialias color</td></tr>
+<tr><td>#5 </td><td>is the dark shadow color</td></tr>
+<tr><td>#6 </td><td>is the light shadow color</td></tr>
+<tr><td>#255 </td><td>is transparent</td></tr>
+</table>
+</dd>
+</ul>
</dl>
<h4>Example</h4>
-
<pre>
- (define-font-colors)
+ (define-font-color 'yellow
+ ; FIXME: what are those? palette index?
+ #( 252 248 240 ; 246
+ 244 224 32 ; 200
+ 208 192 28 ; 199
+ 168 140 16 ; 197
+ 92 48 0 ; 192
+ 0 0 0 ; 239
+ 108 108 108)) ; 104
</pre>
-<p>.
-
-<h4>Used</h4>
-
-<a href="../../data/ccl/fonts.ccl"> $LIBARYPATH/ccl/fonts.ccl </a>
-
<a name="define-menu"></a>
-<h3>define-menu</h3>
+<h3>(define-menu 'tag1 value1 'tag2 value2 ...)</h3>
-<h4>Description</h4>
-
-.
-
-<h4>Syntax</h4>
-
-<code>(define-menu)</code>
+FIXME: incomplete docu<br>
+Possible tags:
<dl>
-<dt></dt>
-<dd>.
+<dt>geometry</dt>
+<dd>'(x y width height)
+</dd>
+<dt>name</dt>
+<dd>Name of this menu.
+</dd>
+<dt>panel</dt>
+<dd>Panel name (FIXME: how is it used?), or 'none.
+</dd>
+<dt>default</dt>
+<dd>An integer. FIXME: what for? Default button, or what?
+</dd>
+<dt>netaction</dt>
+<dd>Eg. 'terminate-net-connect.
</dd>
</dl>
<h4>Example</h4>
-
<pre>
- (define-menu)
+ (define-menu 'name 'menu-sound-options 'geometry '(224 64 352 352)
+ 'panel 'panel5 'default '23)
</pre>
-<p>.
-
-<h4>Used</h4>
-
-<a href="../../data/ccl/menus.ccl"> $LIBARYPATH/ccl/menus.ccl </a>
-
<a name="define-menu-graphics"></a>
-<h3>define-menu-graphics</h3>
-
-<h4>Description</h4>
+<h3>(define-menu-graphics '(file filename size (w h)) ...)</h3>
Define the menu graphics for each of the races.
-<h4>Syntax</h4>
-
-<code>(define-menu-graphics '(file filename size (w h)) ...)</code>
-
<dl>
<dt>filename</dt>
<dd>Path to the file containing the menu graphics.
</dd>
-<dt>w,h</dt>
+<dt>w, h</dt>
<dd>Width and height of an image in the menu graphic.
</dd>
</dl>
<h4>Example</h4>
-
<pre>
(define-menu-graphics
'(file "ui/buttons 1.png" size (300 144))
'(file "ui/buttons 2.png" size (300 144)))
</pre>
-<p>Defines the menu graphics for all races.
-
-<h4>Used</h4>
-
-<a href="../../data/ccl/menus.ccl"> $LIBARYPATH/ccl/menus.ccl </a>
-
<a name="define-menu-item"></a>
-<h3>define-menu-item</h3>
-
-<h4>Description</h4>
-
-.
-
-<h4>Syntax</h4>
-
-<code>(define-menu-item)</code>
-
-<dl>
-<dt></dt>
-<dd>.
-</dd>
-</dl>
-
-<h4>Example</h4>
+<h3>(define-menu-item 'tag1 value1 'tag2 value2 ...)</h3>
+Add an item to a menu. This could be any item, it depends
+on the tags used.<br>
+FIXME: incomplete docu<br>
+Example:
<pre>
- (define-menu-item)
+ (define-menu-item 'pos (list 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>
-<p>.
+Possible tags:
-<h4>Used</h4>
-
-<a href="../../data/ccl/menus.ccl"> $LIBARYPATH/ccl/menus.ccl </a>
+<dl>
+<dt>pos</dt>
+<dd>Position, in the form '(x y).
+</dd>
+<dt>menu</dt>
+<dd>Menu this item belogs to.
+</dd>
+<dt>flags</dt>
+<dd>Most likely '(disabled).
+Other possibilities: '(active), '(clicked), '(selected).
+FIXME: are the paranthesis really needed?
+</dd>
+<dt>font</dt>
+<dd>Font name (see <a href="#define-font">define-font</a>).
+</dd>
+<dt>init</dt>
+<dd>Init function (there are a couple of
+hardcoded C funtions allowed, like 'save-replay-init or
+'scen-select-init).
+</dd>
+<dt>exit</dt>
+<dd>Exit funtion (again some C functions like 'speed-options-exit or
+'load-game-exit).
+</dd>
+<dt>text</dt>
+<dd>The item is a text label. The value is a list of tags, for example:
+<pre>
+ 'text '(caption "Connecting to server" align center)
+</pre>Allowed tags:
+ <dl>
+ <dt>align</dt>
+ <dd>Left, right or center.
+ </dd>
+ <dt>caption</dt>
+ <dd>The text.
+ </dd>
+ <dt>func</dt>
+ <dd>C handler. FIXME: when called?
+ </dd>
+ <dt>color-normal</dt>
+ <dd>FIXME.
+ </dd>
+ <dt>color-reverse</dt>
+ <dd>FIXME.
+ </dd>
+ </dl>
+</dd>
+<dt>button</dt>
+<dd>The item is a button. The value is a list of tags like
+<pre>
+ 'button '(size (224 27)
+ caption "~!Surrender"
+ hotkey "s"
+ func surrender-confirm-menu
+ style gm-full)
+</pre>
+Allowed tags: align, caption, color-normal, color-reverse (see above)
+and:
+ <dl>
+ <dt>size</dt>
+ <dd>Dimensions (width height).
+ </dd>
+ <dt>func</dt>
+ <dd>C handler. FIXME: when called?
+ </dd>
+ <dt>hotkey</dt>
+ <dd>A string like "f8".
+ </dd>
+ <dt>style</dt>
+ <dd>Complete list of possible styles (not all for buttons):<br>
+ main, network, gm-half, 132, gm-full, gem-round, gem-square,
+ up-arrow, down-arrow, left-arrow, right-arrow, s-knob, s-vcont,
+ s-hcont, pulldown, vthin, folder, sc-gem-round, sc-gem-square,
+ sc-up-arrow, sc-down-arrow, sc-left-arrow, sc-right-arrow,
+ sc-s-knob, sc-s-vcont, sc-s-hcont, sc-pulldown, sc-button-left,
+ sc-button, sc-button-right
+ <br>
+ FIXME: describe them
+ </dd>
+ </dl>
+</dd>
+<dt>gem</dt>
+<dd>The item is a gem.
+Example:
+<pre>
+ 'gem '(size (18 18)
+ text "640 x 480"
+ state unchecked
+ func global-options-resolution-gem
+ style gem-round)
+</pre>
+Allowed tags: size func style text color-normal color-reverse (see
+above) and:
+ <dl>
+ <dt>state</dt>
+ <dd>One of unchecked, passive, invisible or checked.
+ </dd>
+ </dl>
+</dd>
+<dt>pulldown</dt>
+<dd>The item is a pulldown menu.
+Example:
+<pre>
+ 'pulldown '(size (152 20)
+ style pulldown
+ func null
+ options ("Forest" "Winter" "Wasteland" "Orc Swamp" )
+ default 0
+ current 0)
+</pre>
+Allowed tags: size state default current (see above) and:
+ <dl>
+ <dt>options</dt>
+ <dd>A list of strings to select from.
+ </dd>
+ <dt>func</dt>
+ <dd>C handler. FIXME: when called?
+ </dd>
+ <dt>state</dt>
+ <dd>The only possible value: passive
+ </dd>
+ <dt>default</dt>
+ <dd>An integer for the default selection id, starting with 0.
+ </dd>
+ <dt>current</dt>
+ <dd>An integer for the current selection id, starting with 0.
+ </dd>
+ </dl>
+</dd>
+<dt>listbox</dt>
+<dd>The item is a list box.
+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>
+Allowed tags: size style default current color-normal color-reverse
+(see above) and:
+ <dl>
+ <dt>func</dt>
+ <dd>C handler. FIXME: when called?
+ </dd>
+ <dt>handler</dt>
+ <dd>C handler. FIXME: when is it called?
+ </dd>
+ <dt>retopt</dt>
+ <dd>C handler to retrieve the list of options, I guess.
+ </dd>
+ <dt>startline</dt>
+ <dd>For scrolling, I guess. Probably only used in savegames.
+ </dd>
+ <dt>nlines</dt>
+ <dd>Number of lines.
+ </dd>
+ </dl>
+</dd>
+<dt>vslider</dt>
+<dd>The item is a vertical slider.
+Example:
+<pre>
+ 'vslider '(size (18 108)
+ func editor-main-load-vs-action
+ handler editor-main-load-ok)
+</pre>
+Allowed tags: size default current style (see above) and:
+ <dl>
+ <dt>func</dt>
+ <dd>C handler. FIXME: when is it called?
+ </dd>
+ <dt>handler</dt>
+ <dd>C handler. FIXME: when is it called?
+ </dd>
+ <dt>flags</dt>
+ <dd>FIXME: never seen this used. Possible values: up, down, left, right, knob, cont
+ </dd>
+ <dt>startline</dt>
+ <dd>For scrolling, I guess. Probably only used in savegames.
+ </dd>
+ <dt>nlines</dt>
+ <dd>Number of lines.
+ </dd>
+ </dl>
+</dd>
+<dt>hslider</dt>
+<dd>The item is a horizontal slider. See vslider above.
+Example:
+<pre>
+ 'hslider '(size (198 18)
+ func master-volume-hs-action
+ handler scen-select-ok)
+</pre>
+</dd>
+<dt>drawfunc</dt>
+<dd>The item is drawn from a C function. The value is the name of the
+function.
+Example:
+<pre>
+ (define-menu-item 'pos (list 0 0) 'font 'game 'init 'game-setup-init
+ 'drawfunc 'game-draw-func
+ 'menu 'menu-custom-game)
+</pre>
+</dd>
+<dt>input</dt>
+<dd>The item is a text input field.
+Example:
+<pre>
+ 'input '(size (212 20)
+ func enter-master-action
+ style pulldown)
+</pre>
+Allowed tags: size func style color-normal color-reverse (see above)
+and:
+ <dl>
+ <dt>maxch</dt>
+ <dd>Maximal number of characters. FIXME: never seen this used.
+ </dd>
+ <dt>func</dt>
+ <dd>C handler, seems to be called when a key is pressed and
+ just checks whether it is RETURN.
+ </dd>
+ </dl>
+</dd>
+</dl>
<a name="define-ui"></a>
-<h3>define-ui</h3>
+<h3>(define-ui 'racename screen-width screen-height 'tag1 value1 'tag2 value2 ...)</h3>
-<h4>Description</h4>
+This defines the position and sizes of the different user interface
+sections. You probably want to make a function that takes the
+resolution and the race as parameter.<br>
+This is from a real example:
+<pre>
+ (define (make-ui race screen_width screen_height)
+ ;; precalculate some ui positions for user interface at the bottom
+ ; map area dimensions
+ (define mapw (* 32 (trunc
+ (/ screen_width 32))))
+ (define maph (* 32 (trunc
+ (/ (- screen_height 176 16 16) 32))))
+ ; | | ^ Ressource line
+ ; | +--- Status line
+ ; +------ Buttons
+ ; panels
+ (define minimapx 0)
+ (define minimapy (+ 16 maph))
+ (define infox (+ minimapx 176))
+ (define infoy minimapy)
+ (define buttonx (+ infox 176))
+ (define buttony infoy)
+ (define fillerx (+ buttonx 176))
+ (define fillery infoy)
+ (define statusx 0)
+ (define statusy (+ infoy 176))
-.
+ (define-ui race screen_width screen_height
+ 'normal-font-color (if (= race 'alliance) 'white 'yellow)
+ ;; ... and all the tags described below ...
+ ))
+ (make-ui 'alliance 640 480)
+ (make-ui 'alliance 800 600)
+ (make-ui 'alliance 1024 768)
+ (make-ui 'alliance 1280 960)
+ (make-ui 'alliance 1600 1200)
+
+ (make-ui 'mythical 640 480)
+ (make-ui 'mythical 800 600)
+ (make-ui 'mythical 1024 768)
+ (make-ui 'mythical 1280 960)
+ (make-ui 'mythical 1600 1200)
+</pre>
-<h4>Syntax</h4>
-
-<code>(define-ui)</code>
+All of those tags should be given:
<dl>
-<dt></dt>
-<dd>.
+<dt>normal-font-color</dt>
+<dd>
+<pre>
+ 'normal-font-color (if (= race 'alliance) 'white 'yellow)
+</pre>
+</dd>
+<dt>reverse-font-color</dt>
+<dd>
+<pre>
+ 'reverse-font-color (if (= race 'alliance) 'yellow 'white)
+</pre>
+</dd>
+<dt>filler</dt>
+<dd>
+<pre>
+ 'filler (list
+ 'file (string-append "graphics/ui/" race "/"
+ (number->string screen_width) "x" (number->string screen_height)
+ "/filler1.png")
+ 'pos (list fillerx fillery))
+</pre>
+</dd>
+<dt>resource-line</dt>
+<dd>
+<pre>
+ 'resource-line (list
+ (string-append "graphics/ui/" race "/"
+ (number->string screen_width) "x" (number->string screen_height)
+ "/resource.png")
+ 0 0)
+</pre>
+</dd>
+<dt>resources</dt>
+<dd>
+<pre>
+ 'resources (list
+ 'gold (list 'file "graphics/ui/gold,wood,oil,mana.png" 'row 0
+ 'pos (list (+ 176 0) 0) 'size '(14 14) 'text-pos (list (+ 176 0 18) 1))
+ 'food (list 'file "graphics/ui/food.png" 'row 0
+ 'pos (list (- screen_width 16 138) 0) 'size '(14 14) 'text-pos (list (+ (- screen_width 16 138) 18) 1))
+ 'score (list 'file "graphics/ui/score.png" 'row 0
+ 'pos (list (- screen_width 16 68) 0) 'size '(14 14) 'text-pos (list (+ (- screen_width 16 68) 18) 1)))
+</pre>
+</dd>
+<dt>info-panel</dt>
+<dd>
+<pre>
+ 'info-panel (list
+ (string-append "graphics/ui/" race "/infopanel.png")
+ infox infoy 176 176)
+</pre>
+</dd>
+<dt>completed-bar</dt>
+<dd>
+<pre>
+ 'completed-bar (list
+ 'color 149
+ 'pos (list (+ infox 14) (+ infoy 151))
+ 'size '(152 14)
+ 'text "% Complete"
+ 'font 'game
+ 'text-pos (list (+ infox 14 38) (+ infoy 151)))
+</pre>
+</dd>
+<dt>button-panel</dt>
+<dd>
+<pre>
+ 'button-panel (list
+ (string-append "graphics/ui/" race "/buttonpanel.png")
+ buttonx buttony)
+</pre>
+</dd>
+<dt>map-area</dt>
+<dd>
+<pre>
+ 'map-area (list
+ 'pos '(0 16)
+ 'size (list mapw maph))
+</pre>
+</dd>
+<dt>menu-panel</dt>
+<dd>
+<pre>
+ 'menu-panel (list
+ (string-append "graphics/ui/" race "/menubutton.png")
+ minimapx (+ minimapy 148))
+</pre>
+</dd>
+<dt>minimap-panel</dt>
+<dd>
+<pre>
+ 'minimap-panel (list
+ (string-append "graphics/ui/" race "/minimap.png")
+ minimapx minimapy)
+</pre>
+</dd>
+<dt>minimap-pos</dt>
+<dd>
+<pre>
+ 'minimap-pos (list
+ (+ minimapx 27) (+ minimapy 13))
+</pre>
+</dd>
+<dt>status-line</dt>
+<dd>
+<pre>
+ 'status-line (list
+ 'file (string-append "graphics/ui/" race "/"
+ (number->string screen_width) "x" (number->string screen_height)
+ "/statusline.png")
+ 'pos (list statusx statusy)
+ 'text-pos (list (+ statusx 6) (+ statusy 2))
+ 'font 'game)
+</pre>
+</dd>
+<dt>menu-button</dt>
+<dd>
+<pre>
+ 'menu-button (list
+ 'pos (list (+ minimapx 28) (+ minimapy 148))
+ 'size '(128 19)
+ 'caption "Menu (~<F10~>)"
+ 'style 'main)
+</pre>
+</dd>
+<dt>network-menu-button</dt>
+<dd>
+<pre>
+ 'network-menu-button '(
+ pos (6 2)
+ size (80 19)
+ caption "Menu"
+ style network)
+</pre>
+</dd>
+<dt>network-diplomacy-button</dt>
+<dd>
+<pre>
+ 'network-diplomacy-button '(
+ pos (90 2)
+ size (80 19)
+ caption "Diplomacy"
+ style network)
+</pre>
+</dd>
+<dt>info-buttons</dt>
+<dd>Position of the unit icons on the info panel. Example:
+<pre>
+ 'info-buttons (list
+ (list 'pos (list (+ infox 9) (+ infoy 8)) 'size '(46 38))
+ (list 'pos (list (+ infox 65) (+ infoy 8)) 'size '(46 38))
+ (list 'pos (list (+ infox 121) (+ infoy 8)) 'size '(46 38))
+ (list 'pos (list (+ infox 9) (+ infoy 62)) 'size '(46 38))
+ (list 'pos (list (+ infox 65) (+ infoy 62)) 'size '(46 38))
+ (list 'pos (list (+ infox 121) (+ infoy 62)) 'size '(46 38))
+ (list 'pos (list (+ infox 9) (+ infoy 116)) 'size '(46 38))
+ (list 'pos (list (+ infox 65) (+ infoy 116)) 'size '(46 38))
+ (list 'pos (list (+ infox 121) (+ infoy 116)) 'size '(46 38)))
+</pre>
+</dd>
+<dt>training-buttons</dt>
+<dd>Position of the unit icons in the training queue. Should be the
+same positions as info-buttons above but without the last
+three. (FIXME: is this a requirement?)
+</dd>
+<dt>button-buttons</dt>
+<dd>Position of the action buttons (attack, move, etc.). Currently
+there must be nine of them, and they must be on the button panel. Same
+syntax as above.
+</dd>
+<dt>cursors</dt>
+<dd>
+<pre>
+ 'cursors '(
+ point cursor-point
+ glass cursor-glass
+ cross cursor-cross
+ yellow cursor-yellow-hair
+ green cursor-green-hair
+ red cursor-red-hair
+ scroll cursor-scroll
+ arrow-e cursor-arrow-e
+ arrow-ne cursor-arrow-ne
+ arrow-n cursor-arrow-n
+ arrow-nw cursor-arrow-nw
+ arrow-w cursor-arrow-w
+ arrow-sw cursor-arrow-sw
+ arrow-s cursor-arrow-s
+ arrow-se cursor-arrow-se)
+</pre>
+</dd>
+<dt>menu-panels</dt>
+<dd>FIXME: this really needs docu or change, if you dig out the
+requirement of the pictures, write them down here. Example:
+<pre>
+ 'menu-panels (list
+ 'panel1 (string-append "graphics/ui/" race "/panel_1.png")
+ 'panel2 (string-append "graphics/ui/" race "/panel_2.png")
+ 'panel3 (string-append "graphics/ui/" race "/panel_3.png")
+ 'panel4 (string-append "graphics/ui/" race "/panel_4.png")
+ 'panel5 (string-append "graphics/ui/" race "/panel_5.png"))
+</pre>
+</dd>
+<dt>victory-background</dt>
+<dd>Background image for the victory screen. The image will be scaled. Example:
+<pre>
+ 'victory-background (string-append "graphics/ui/" race "/victory.png")
+</pre>
+</dd>
+<dt>defeat-background</dt>
+<dd>Background image for the victory screen. The image will be scaled. Example:
+<pre>
+ 'defeat-background (string-append "graphics/ui/" race "/defeat.png")
+</pre>
</dd>
</dl>
-<h4>Example</h4>
-
-<pre>
- (define-ui)
-</pre>
-
-<p>.
-
-<h4>Used</h4>
-
-<a href="../../data/ccl/wc2.ccl"> $LIBARYPATH/ccl/wc2.ccl </a>
-
<a name="define-viewports"></a>
-<h3>define-viewports</h3>
+<h3>(define-viewports 'mode mode 'viewport (mapx mapy) ...)</h3>
-<h4>Description</h4>
-
-Define the viewports.
-
-<h4>Syntax</h4>
-
-<code>(define-viewports 'mode mode 'viewport (mapx mapy) ...)</code>
+Define the viewports. Only used in savegames, but could be useful for
+scenarios.
<dl>
<dt>mode</dt>
@@ -397,29 +813,22 @@ Define the viewports.
</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.
(define-viewports 'mode 1
'viewport '(82 31)
'viewport '(64 31))
</pre>
-<p>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.
<h4>Not Used</h4>
<a name="display-picture"></a>
-<h3>display-picture</h3>
-
-<h4>Description</h4>
+<h3>(display-picture file)</h3>
Display a picture.
-<h4>Syntax</h4>
-
-<code>(display-picture file)</code>
<dl>
<dt>file</dt>
@@ -438,15 +847,10 @@ Display a picture.
<h4>Not Used</h4>
<a name="process-menu"></a>
-<h3>process-menu</h3>
-
-<h4>Description</h4>
+<h3>(process-menu id)</h3>
Process a menu.
-<h4>Syntax</h4>
-
-<code>(process-menu id)</code>
<dl>
<dt>id</dt>
@@ -465,15 +869,10 @@ Process a menu.
<h4>Not Used</h4>
<a name="set-game-cursor!"></a>
-<h3>set-game-cursor!</h3>
-
-<h4>Description</h4>
+<h3>(set-game-cursor! ident)</h3>
Set the game cursor.
-<h4>Syntax</h4>
-
-<code>(set-game-cursor! ident)</code>
<dl>
<dt>ident</dt>