summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorrubidium <rubidium@openttd.org>2008-08-01 09:34:34 +0000
committerrubidium <rubidium@openttd.org>2008-08-01 09:34:34 +0000
commitc5a4e90338c4f66dfd75497b5137b4fd0a7da867 (patch)
tree2ff51cc080d35422ab3d268a167cf4863270082e
parent47592b92883416e782df54604bbe3156e3aa9daf (diff)
downloadopenttd-c5a4e90338c4f66dfd75497b5137b4fd0a7da867.tar.xz
(svn r13910) -Document: string drawing related functions and types (Alberth)
-rw-r--r--src/core/bitmath_func.hpp18
-rw-r--r--src/gfx.cpp159
-rw-r--r--src/gfx_func.h5
-rw-r--r--src/gfx_type.h3
-rw-r--r--src/strings_type.h9
-rw-r--r--src/table/control_codes.h4
-rw-r--r--src/widget.cpp22
-rw-r--r--src/window_gui.h4
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
};
/**