(svn r13910) -Document: string drawing related functions and types (Alberth)

8 files changed, 194 insertions, 30 deletions

diff --git a/src/core/bitmath_func.hpp b/src/core/bitmath_func.hpp
index 167a863c8..6abcdcb80 100644
--- a/src/core/bitmath_func.hpp
+++ b/src/core/bitmath_func.hpp
@@ -27,22 +27,22 @@ static FORCEINLINE uint GB(const T x, const uint8 s, const uint8 n)
 	return (x >> s) & ((1U << n) - 1);
 }
 
-/** Set n bits from x starting at bit s to d
+/** Set \a n bits in \a x starting at bit \a s to \a d
  *
- * This function sets n bits from x which started as bit s to the value of
- * d. The parameters x, s and n works the same as the parameters of
- * #GB. The result is saved in x again. Unused bits in the window
- * provided by n are set to 0 if the value of b isn't "big" enough.
+ * This function sets \a n bits from \a x which started as bit \a s to the value of
+ * \a d. The parameters \a x, \a s and \a n works the same as the parameters of
+ * #GB. The result is saved in \a x again. Unused bits in the window
+ * provided by n are set to 0 if the value of \a d isn't "big" enough.
  * This is not a bug, its a feature.
  *
- * @note Parameter x must be a variable as the result is saved there.
- * @note To avoid unexpecting results the value of b should not use more
- *       space as the provided space of n bits (log2)
+ * @note Parameter \a x must be a variable as the result is saved there.
+ * @note To avoid unexpecting results the value of \a d should not use more
+ *       space as the provided space of \a n bits (log2)
  * @param x The variable to change some bits
  * @param s The startposition for the new bits
  * @param n The size/window for the new bits
  * @param d The actually new bits to save in the defined position.
- * @return The new value of x
+ * @return The new value of \a x
  */
 template <typename T, typename U>
 static FORCEINLINE T SB(T &x, const uint8 s, const uint8 n, const U d)
diff --git a/src/gfx.cpp b/src/gfx.cpp
index 3b9b042eb..73363bb6a 100644
--- a/src/gfx.cpp
+++ b/src/gfx.cpp
@@ -45,7 +45,7 @@ int _pal_first_dirty;
 int _pal_count_dirty;
 
 Colour _cur_palette[256];
-byte _stringwidth_table[FS_END][224];
+byte _stringwidth_table[FS_END][224]; ///< Cache containing width of often used characters. @see GetCharacterWidth()
 DrawPixelInfo *_cur_dpi;
 byte _colour_gradient[16][8];
 bool _use_dos_palette;
@@ -288,13 +288,32 @@ static int TruncateString(char *str, int maxw)
 	return w;
 }
 
+/**
+ * Write string to output buffer, truncating it to specified maximal width in pixels if it is too long.
+ *
+ * @param src   String to truncate
+ * @param dest  Start of character output buffer where truncated string is stored
+ * @param maxw  Maximal allowed length of the string in pixels
+ * @param last  Address of last character in output buffer
+ *
+ * @return Actual width of the (possibly) truncated string in pixels
+ */
 static inline int TruncateStringID(StringID src, char *dest, int maxw, const char* last)
 {
 	GetString(dest, src, last);
 	return TruncateString(dest, maxw);
 }
 
-/* returns right coordinate */
+/**
+ * Draw string starting at position (x,y).
+ *
+ * @param x      X position to start drawing
+ * @param y      Y position to start drawing
+ * @param str    String to draw
+ * @param color  Color used for drawing the string, see DoDrawString() for details
+ *
+ * @return Horizontal coordinate after drawing the string
+ */
 int DrawString(int x, int y, StringID str, uint16 color)
 {
 	char buffer[512];
@@ -303,6 +322,17 @@ int DrawString(int x, int y, StringID str, uint16 color)
 	return DoDrawString(buffer, x, y, color);
 }
 
+/**
+ * Draw string, possibly truncated to make it fit in its allocated space
+ *
+ * @param x      X position to start drawing
+ * @param y      Y position to start drawing
+ * @param str    String to draw
+ * @param color  Color used for drawing the string, see DoDrawString() for details
+ * @param maxw   Maximal width of the string
+ *
+ * @return Horizontal coordinate after drawing the (possibly truncated) string
+ */
 int DrawStringTruncated(int x, int y, StringID str, uint16 color, uint maxw)
 {
 	char buffer[512];
@@ -310,7 +340,16 @@ int DrawStringTruncated(int x, int y, StringID str, uint16 color, uint maxw)
 	return DoDrawString(buffer, x, y, color);
 }
 
-
+/**
+ * Draw string right-aligned.
+ *
+ * @param x      Right-most x position of the string
+ * @param y      Y position of the string
+ * @param str    String to draw
+ * @param color  Color used for drawing the string, see DoDrawString() for details
+ *
+ * @return Width of drawn string in pixels
+ */
 int DrawStringRightAligned(int x, int y, StringID str, uint16 color)
 {
 	char buffer[512];
@@ -323,6 +362,15 @@ int DrawStringRightAligned(int x, int y, StringID str, uint16 color)
 	return w;
 }
 
+/**
+ * Draw string right-aligned, possibly truncated to make it fit in its allocated space
+ *
+ * @param x      Right-most x position to start drawing
+ * @param y      Y position to start drawing
+ * @param str    String to draw
+ * @param color  Color used for drawing the string, see DoDrawString() for details
+ * @param maxw   Maximal width of the string
+ */
 void DrawStringRightAlignedTruncated(int x, int y, StringID str, uint16 color, uint maxw)
 {
 	char buffer[512];
@@ -331,13 +379,30 @@ void DrawStringRightAlignedTruncated(int x, int y, StringID str, uint16 color, u
 	DoDrawString(buffer, x - GetStringBoundingBox(buffer).width, y, color);
 }
 
+/**
+ * Draw string right-aligned with a line underneath it.
+ *
+ * @param x      Right-most x position of the string
+ * @param y      Y position of the string
+ * @param str    String to draw
+ * @param color  Color used for drawing the string, see DoDrawString() for details
+ */
 void DrawStringRightAlignedUnderline(int x, int y, StringID str, uint16 color)
 {
 	int w = DrawStringRightAligned(x, y, str, color);
 	GfxFillRect(x - w, y + 10, x, y + 10, _string_colorremap[1]);
 }
 
-
+/**
+ * Draw string centered.
+ *
+ * @param x      X position of center of the string
+ * @param y      Y position of center of the string
+ * @param str    String to draw
+ * @param color  Color used for drawing the string, see DoDrawString() for details
+ *
+ * @return Width of the drawn string in pixels
+ */
 int DrawStringCentered(int x, int y, StringID str, uint16 color)
 {
 	char buffer[512];
@@ -351,6 +416,17 @@ int DrawStringCentered(int x, int y, StringID str, uint16 color)
 	return w;
 }
 
+/**
+ * Draw string centered, possibly truncated to fit in the assigned space.
+ *
+ * @param xl     Left-most x position
+ * @param xr     Right-most x position
+ * @param y      Y position of the string
+ * @param str    String to draw
+ * @param color  Color used for drawing the string, see DoDrawString() for details
+ *
+ * @return Right-most coordinate of the (possibly truncated) drawn string
+ */
 int DrawStringCenteredTruncated(int xl, int xr, int y, StringID str, uint16 color)
 {
 	char buffer[512];
@@ -358,6 +434,16 @@ int DrawStringCenteredTruncated(int xl, int xr, int y, StringID str, uint16 colo
 	return DoDrawString(buffer, (xl + xr - w) / 2, y, color);
 }
 
+/**
+ * Draw string centered.
+ *
+ * @param x      X position of center of the string
+ * @param y      Y position of center of the string
+ * @param str    String to draw
+ * @param color  Color used for drawing the string, see DoDrawString() for details
+ *
+ * @return Width of the drawn string in pixels
+ */
 int DoDrawStringCentered(int x, int y, const char *str, uint16 color)
 {
 	int w = GetStringBoundingBox(str).width;
@@ -365,12 +451,29 @@ int DoDrawStringCentered(int x, int y, const char *str, uint16 color)
 	return w;
 }
 
+/**
+ * Draw string centered, with additional line underneath it
+ *
+ * @param x      X position of center of the string
+ * @param y      Y position of center of the string
+ * @param str    String to draw
+ * @param color  Color used for drawing the string, see DoDrawString() for details
+ */
 void DrawStringCenterUnderline(int x, int y, StringID str, uint16 color)
 {
 	int w = DrawStringCentered(x, y, str, color);
 	GfxFillRect(x - (w >> 1), y + 10, x - (w >> 1) + w, y + 10, _string_colorremap[1]);
 }
 
+/**
+ * Draw string centered possibly truncated, with additional line underneath it
+ *
+ * @param xl     Left x position of the string
+ * @param xr     Right x position of the string
+ * @param y      Y position of center of the string
+ * @param str    String to draw
+ * @param color  Color used for drawing the string, see DoDrawString() for details
+ */
 void DrawStringCenterUnderlineTruncated(int xl, int xr, int y, StringID str, uint16 color)
 {
 	int w = DrawStringCenteredTruncated(xl, xr, y, str, color);
@@ -638,6 +741,13 @@ Dimension GetStringBoundingBox(const char *str)
 	return br;
 }
 
+/**
+ * Draw single character horizontally centered around (x,y)
+ * @param c           Character (glyph) to draw
+ * @param x           X position to draw character
+ * @param y           Y position to draw character
+ * @param real_color  Colour to use, see DoDrawString() for details
+ */
 void DrawCharCentered(WChar c, int x, int y, uint16 real_color)
 {
 	FontSize size = FS_NORMAL;
@@ -653,13 +763,13 @@ void DrawCharCentered(WChar c, int x, int y, uint16 real_color)
 }
 
 /** Draw a string at the given coordinates with the given colour
- * @param string the string to draw
- * @param x offset from left side of the screen, if negative offset from the right side
- * @param y offset from top side of the screen, if negative offset from the bottom
- * @param real_color colour of the string, see _string_colormap in
- * table/palettes.h or docs/ottd-colourtext-palette.png or the enum TextColour in gfx_type.h
+ * @param string     The string to draw
+ * @param x          Offset from left side of the screen, if negative offset from the right side
+ * @param y          Offset from top side of the screen, if negative offset from the bottom
+ * @param real_color Colour of the string, see _string_colormap in
+ *                   table/palettes.h or docs/ottd-colourtext-palette.png or the enum TextColour in gfx_type.h
  * @return the x-coordinates where the drawing has finished. If nothing is drawn
- * the originally passed x-coordinate is returned */
+ *         the originally passed x-coordinate is returned */
 int DoDrawString(const char *string, int x, int y, uint16 real_color)
 {
 	DrawPixelInfo *dpi = _cur_dpi;
@@ -739,6 +849,18 @@ skip_cont:;
 	}
 }
 
+/**
+ * Draw the string of the character buffer, starting at position (x,y) with a given maximal width.
+ * String is truncated if it is too long.
+ *
+ * @param str  Character buffer containing the string
+ * @param x    Left-most x coordinate to start drawing
+ * @param y    Y coordinate to draw the string
+ * @param color Colour to use, see DoDrawString() for details.
+ * @param maxw  Maximal width in pixels that may be used for drawing
+ *
+ * @return Right-most x position after drawing the (possibly truncated) string
+ */
 int DoDrawStringTruncated(const char *str, int x, int y, uint16 color, uint maxw)
 {
 	char buffer[512];
@@ -747,6 +869,14 @@ int DoDrawStringTruncated(const char *str, int x, int y, uint16 color, uint maxw
 	return DoDrawString(buffer, x, y, color);
 }
 
+/**
+ * Draw a sprite.
+ * @param img  Image number to draw
+ * @param pal  Palette to use.
+ * @param x    Left coordinate of image
+ * @param y    Top coordinate of image
+ * @param sub  If available, draw only specified part of the sprite
+ */
 void DrawSprite(SpriteID img, SpriteID pal, int x, int y, const SubSprite *sub)
 {
 	if (HasBit(img, PALETTE_MODIFIER_TRANSPARENT)) {
@@ -979,6 +1109,7 @@ void DoPaletteAnimations()
 }
 
 
+/** Initialize _stringwidth_table cache */
 void LoadStringWidthTable()
 {
 	uint i;
@@ -999,9 +1130,15 @@ void LoadStringWidthTable()
 	}
 }
 
-
+/**
+ * Return width of character glyph.
+ * @param size  Font of the character
+ * @param key   Character code glyph
+ * @return Width of the character glyph
+ */
 byte GetCharacterWidth(FontSize size, WChar key)
 {
+	/* Use _stringwidth_table cache if possible */
 	if (key >= 32 && key < 256) return _stringwidth_table[size][key - 32];
 
 	return GetGlyphWidth(size, key);
diff --git a/src/gfx_func.h b/src/gfx_func.h
index 51986a71f..12f042c25 100644
--- a/src/gfx_func.h
+++ b/src/gfx_func.h
@@ -151,6 +151,11 @@ extern FontSize _cur_fontsize;
 
 byte GetCharacterWidth(FontSize size, uint32 key);
 
+/**
+ * Get height of a character for a given font size.
+ * @param size Font size to get height of
+ * @return     Height of characters in the given font (pixels)
+ */
 static inline byte GetCharacterHeight(FontSize size)
 {
 	switch (size) {
diff --git a/src/gfx_type.h b/src/gfx_type.h
index 4d5a3654a..a85a32434 100644
--- a/src/gfx_type.h
+++ b/src/gfx_type.h
@@ -11,6 +11,7 @@
 #include "zoom_type.h"
 
 typedef uint32 SpriteID;      ///< The number of a sprite, without mapping bits and colortables
+
 struct PalSpriteID {
 	SpriteID sprite;
 	SpriteID pal;
@@ -110,6 +111,7 @@ struct AnimCursor {
 	byte display_time; ///< Amount of ticks this sprite will be shown
 };
 
+/** Collection of variables for cursor-display and -animation */
 struct CursorVars {
 	Point pos, size, offs, delta; ///< position, size, offset from top-left, and movement
 	Point draw_pos, draw_size;    ///< position and size bounding-box for drawing
@@ -153,6 +155,7 @@ struct Colour {
 	operator uint32 () const { return *(uint32 *)this; }
 };
 
+/** Available font sizes */
 enum FontSize {
 	FS_NORMAL,
 	FS_SMALL,
diff --git a/src/strings_type.h b/src/strings_type.h
index d9482f23d..00c7d6538 100644
--- a/src/strings_type.h
+++ b/src/strings_type.h
@@ -5,11 +5,14 @@
 #ifndef STRINGS_TYPE_H
 #define STRINGS_TYPE_H
 
+/**
+ * Numeric value that represents a string, independent of the selected language.
+ */
 typedef uint16 StringID;
-static const StringID INVALID_STRING_ID = 0xFFFF;
+static const StringID INVALID_STRING_ID = 0xFFFF;  ///< Constant representing an invalid string
 
 enum {
-	MAX_LANG = 64,
+	MAX_LANG = 64, ///< Maximal number of languages supported by the game
 };
 
 /** Information about a language */
@@ -26,7 +29,7 @@ struct DynamicLanguages {
 	Language ent[MAX_LANG];   ///< Information about the languages
 };
 
-// special string constants
+/** Special string constants */
 enum SpecialStrings {
 
 	// special strings for town names. the town name is generated dynamically on request.
diff --git a/src/table/control_codes.h b/src/table/control_codes.h
index b35129960..69cabda67 100644
--- a/src/table/control_codes.h
+++ b/src/table/control_codes.h
@@ -19,8 +19,8 @@ enum StringControlCode {
 	/* Display control codes */
 	SCC_SETX = SCC_CONTROL_START,
 	SCC_SETXY,
-	SCC_TINYFONT,
-	SCC_BIGFONT,
+	SCC_TINYFONT,  ///< Switch to small font
+	SCC_BIGFONT,   ///< Switch to large font
 
 	/* Formatting control codes */
 	SCC_REVISION,
diff --git a/src/widget.cpp b/src/widget.cpp
index 47e6f7097..92c402e5d 100644
--- a/src/widget.cpp
+++ b/src/widget.cpp
@@ -17,13 +17,21 @@
 static const char *UPARROW   = "\xEE\x8A\xA0";
 static const char *DOWNARROW = "\xEE\x8A\xAA";
 
+/**
+ * Compute the vertical position of the draggable part of scrollbar
+ * @param sb     Scrollbar list data
+ * @param top    Top position of the scrollbar (top position of the up-button)
+ * @param bottom Bottom position of the scrollbar (bottom position of the down-button)
+ * @return A Point, with x containing the top coordinate of the draggable part, and
+ *                       y containing the bottom coordinate of the draggable part
+ */
 static Point HandleScrollbarHittest(const Scrollbar *sb, int top, int bottom)
 {
 	Point pt;
 	int height, count, pos, cap;
 
-	top += 10;
-	bottom -= 9;
+	top += 10;   // top    points to just below the up-button
+	bottom -= 9; // bottom points to top of the down-button
 
 	height = (bottom - top);
 
@@ -153,7 +161,15 @@ int GetWidgetFromPos(const Window *w, int x, int y)
 	return found_index;
 }
 
-
+/**
+ * Draw frame rectangle.
+ * @param left   Left edge of the frame
+ * @param top    Top edge of the frame
+ * @param right  Right edge of the frame
+ * @param bottom Bottom edge of the frame
+ * @param ctab   Colour table to use. @see _colour_gradient
+ * @param flags  Flags controlling how to draw the frame. @see FrameFlags
+ */
 void DrawFrameRect(int left, int top, int right, int bottom, int ctab, FrameFlags flags)
 {
 	uint dark         = _colour_gradient[ctab][3];
diff --git a/src/window_gui.h b/src/window_gui.h
index 7d58962d6..87b7b381c 100644
--- a/src/window_gui.h
+++ b/src/window_gui.h
@@ -80,7 +80,7 @@ enum {
  */
 struct Widget {
 	byte type;                        ///< Widget type, see WindowWidgetTypes
-	byte display_flags;               ///< Resize direction, alignment, etc. during resizing, see ResizeFlags
+	byte display_flags;               ///< Resize direction, alignment, etc. during resizing. @see ResizeFlags
 	byte color;                       ///< Widget colour, see docs/ottd-colourtext-palette.png
 	int16 left, right, top, bottom;   ///< The position offsets inside the window
 	uint16 data;                      ///< The String/Image or special code (list-matrixes) of a widget
@@ -149,7 +149,7 @@ enum WindowDefaultPosition {
 struct Scrollbar {
 	uint16 count;  ///< Number of elements in the list
 	uint16 cap;    ///< Number of visible elements of the scroll bar
-	uint16 pos;
+	uint16 pos;    ///< Index of first visible item of the list
 };
 
 /**