2.2.3. String drawing functions
- Setting the default background flag
- Getting the default background flag
- Setting the default alignment
- Getting the default alignment
- Printing a string with default parameters
- Printing a string with specific alignment and background mode
- Printing a string with default parameters and autowrap
- Printing a string with specific alignment and background mode and autowrap
- Compute the height of an autowrapped string
- Changing the colors while printing a string
- Unicode functions
Setting the default background flag
This function defines the background mode (see TCOD_bkgnd_flag_t) for the console.
This default mode is used by several functions (print, printRect, ...)
void TCODConsole::setBackgroundFlag(TCOD_bkgnd_flag_t flag)
void TCOD_console_set_background_flag(TCOD_console_t con,TCOD_bkgnd_flag_t flag)
console_set_background_flag(con, flag)
void TCODConsole::setBackgroundFlag(TCODBackgroundFlag flag)
Console:setBackgroundFlag(flag)
Parameter | Description |
---|---|
con | in the C and Python versions, the offscreen console handler or NULL for the root console |
flag | this flag defines how the cell's background color is modified. See TCOD_bkgnd_flag_t |
Getting the default background flag
This function returns the background mode (see TCOD_bkgnd_flag_t) for the console.
This default mode is used by several functions (print, printRect, ...)
TCOD_bkgnd_flag_t TCODConsole::getBackgroundFlag() const
TCOD_bkgnd_flag_t TCOD_console_get_background_flag(TCOD_console_t con)
console_get_background_flag(con)
TCODBackgroundFlag TCODConsole::getBackgroundFlag()
Console:getBackgroundFlag()
Parameter | Description |
---|---|
con | in the C and Python versions, the offscreen console handler or NULL for the root console |
Setting the default alignment
This function defines the default alignment (see TCOD_alignment_t) for the console.
This default alignment is used by several functions (print, printRect, ...).
Values for alignment : TCOD_LEFT, TCOD_CENTER, TCOD_RIGHT (in python, remove TCOD_ : libtcod.LEFT).
For C# and Lua : LeftAlignment, RightAlignment, CenterAlignment
void TCODConsole::setAlignment(TCOD_alignment_t alignment)
void TCOD_console_set_alignment(TCOD_console_t con,TCOD_bkgnd_flag_t alignment)
console_set_alignment(con, alignment)
void TCODConsole::setAlignment(TCODAlignment alignment)
Console:setAlignment(alignment)
Parameter | Description |
---|---|
con | in the C and Python versions, the offscreen console handler or NULL for the root console |
alignment | defines how the strings are printed on screen. |
Getting the default alignment
This function returns the default alignment (see TCOD_alignment_t) for the console.
This default mode is used by several functions (print, printRect, ...).
Values for alignment : TCOD_LEFT, TCOD_CENTER, TCOD_RIGHT (in python, remove TCOD_ : libtcod.LEFT).
For C# and Lua : LeftAlignment, RightAlignment, CenterAlignment
TCOD_alignment_t TCODConsole::getAlignment() const
TCOD_alignment_t TCOD_console_get_alignment(TCOD_console_t con)
console_get_alignment(con)
TCODAlignment TCODConsole::getAlignment()
Console:getAlignment()
Parameter | Description |
---|---|
con | in the C and Python versions, the offscreen console handler or NULL for the root console |
Printing a string with default parameters
This function print a string at a specific position using current default alignment, background flag, foreground and background colors.
void TCODConsole::print(int x, int y, const char *fmt, ...)
void TCOD_console_print(TCOD_console_t con,int x, int y, const char *fmt, ...)
console_print(con, x, y, fmt)
void TCODConsole::print(int x, int y, string fmt)
Console:print(x, y, fmt)
Parameter | Description |
---|---|
con | in the C and Python versions, the offscreen console handler or NULL for the root console |
x,y | coordinate of the character in the console, depending on the default alignment for this console : * TCOD_LEFT : leftmost character of the string * TCOD_CENTER : center character of the string * TCOD_RIGHT : rightmost character of the string |
fmt | printf-like format string, eventually followed by parameters. You can use control codes to change the colors inside the string, except in C#. |
Printing a string with specific alignment and background mode
This function print a string at a specific position using specific alignment and background flag, but default foreground and background colors.
void TCODConsole::printEx(int x, int y, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const char *fmt, ...)
void TCOD_console_print_ex(TCOD_console_t con,int x, int y, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const char *fmt, ...)
console_print_ex(con, x, y, flag, alignment, fmt)
void TCODConsole::printEx(int x, int y, TCODBackgroundFlag flag, TCODAlignment alignment, string fmt)
Console::printEx(x, y, flag, alignment, fmt)
Parameter | Description |
---|---|
con | in the C and Python versions, the offscreen console handler or NULL for the root console |
x,y | coordinate of the character in the console, depending on the alignment : * TCOD_LEFT : leftmost character of the string * TCOD_CENTER : center character of the string * TCOD_RIGHT : rightmost character of the string |
flag | this flag defines how the cell's background color is modified. See TCOD_bkgnd_flag_t |
alignment | defines how the strings are printed on screen. |
fmt | printf-like format string, eventually followed by parameters. You can use control codes to change the colors inside the string, except in C#. |
Printing a string with default parameters and autowrap
This function draws a string in a rectangle inside the console, using default colors, alignment and background mode.
If the string reaches the borders of the rectangle, carriage returns are inserted.
If h > 0 and the bottom of the rectangle is reached, the string is truncated. If h = 0, the string is only truncated if it reaches the bottom of the console.
The function returns the height (number of console lines) of the printed string.
int TCODConsole::printRect(int x, int y, int w, int h, const char *fmt, ...)
int TCOD_console_print_rect(TCOD_console_t con,int x, int y, int w, int h, const char *fmt, ...)
console_print_rect(con, x, y, w, h, fmt)
int TCODConsole::printRect(int x, int y, int w, int h, string fmt)
Console:printRect(x, y, w, h, fmt)
Parameter | Description |
---|---|
con | in the C and Python versions, the offscreen console handler or NULL for the root console |
x,y | coordinate of the character in the console, depending on the alignment : * TCOD_LEFT : leftmost character of the string * TCOD_CENTER : center character of the string * TCOD_RIGHT : rightmost character of the string |
w,h | size of the rectangle x <= x+w < console width y <= y+h < console height |
fmt | printf-like format string, eventually followed by parameters. You can use control codes to change the colors inside the string, except in C#. |
Printing a string with specific alignment and background mode and autowrap
This function draws a string in a rectangle inside the console, using default colors, but specific alignment and background mode.
If the string reaches the borders of the rectangle, carriage returns are inserted.
If h > 0 and the bottom of the rectangle is reached, the string is truncated. If h = 0, the string is only truncated if it reaches the bottom of the console.
The function returns the height (number of console lines) of the printed string.
int TCODConsole::printRectEx(int x, int y, int w, int h, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const char *fmt, ...)
int TCOD_console_print_rect_ex(TCOD_console_t con,int x, int y, int w, int h, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const char *fmt, ...)
console_print_rect_ex(con, x, y, w, h, flag, alignment, fmt)
int TCODConsole::printRectEx(int x, int y, int w, int h, TCODBackgroundFlag flag, TCODAlignment alignment, string fmt)
Console:printRectEx(x, y, w, h, flag, alignment, fmt)
Parameter | Description |
---|---|
con | in the C and Python versions, the offscreen console handler or NULL for the root console |
x,y | coordinate of the character in the console, depending on the alignment : * TCOD_LEFT : leftmost character of the string * TCOD_CENTER : center character of the string * TCOD_RIGHT : rightmost character of the string |
w,h | size of the rectangle x <= x+w < console width y <= y+h < console height |
flag | this flag defines how the cell's background color is modified. See TCOD_bkgnd_flag_t |
alignment | defines how the strings are printed on screen. |
fmt | printf-like format string, eventually followed by parameters. You can use control codes to change the colors inside the string, except in C#. |
Compute the height of an autowrapped string
This function returns the expected height of an autowrapped string without actually printing the string with printRect or printRectEx
int TCODConsole::getHeightRect(int x, int y, int w, int h, const char *fmt, ...)
int TCOD_console_get_height_rect(TCOD_console_t con,int x, int y, int w, int h, const char *fmt, ...)
console_get_height_rect(con, x, y, w, h, fmt)
int TCODConsole::getHeightRect(int x, int y, int w, int h, string fmt)
Console:getHeightRect(x, y, w, h, fmt)
Parameter | Description |
---|---|
con | in the C and Python versions, the offscreen console handler or NULL for the root console |
x,y | coordinate of the rectangle upper-left corner in the console |
w,h | size of the rectangle x <= x+w < console width y <= y+h < console height |
fmt | printf-like format string, eventually followed by parameters. You can use control codes to change the colors inside the string, except in C#. |
Changing the colors while printing a string
If you want to draw a string using different colors for each word, the basic solution is to call a string printing function several times, changing the default colors between each call.
The TCOD library offers a simpler way to do this, allowing you to draw a string using different colors in a single call. For this, you have to insert color control codes in your string.
A color control code is associated with a color set (a foreground color and a background color). If you insert this code in your string, the next characters will use the colors associated with the color control code.
There are 5 predefined color control codes :
For python, remove TCOD_ : libtcod.COLCTRL_1
TCOD_COLCTRL_1
TCOD_COLCTRL_2
TCOD_COLCTRL_3
TCOD_COLCTRL_4
TCOD_COLCTRL_5
To associate a color with a code, use setColorControl.
To go back to the console's default colors, insert in your string the color stop control code :
TCOD_COLCTRL_STOP
You can also use any color without assigning it to a control code, using the generic control codes :
TCOD_COLCTRL_FORE_RGB
TCOD_COLCTRL_BACK_RGB
Those controls respectively change the foreground and background color used to print the string characters. In the string, you must insert the r,g,b components of the color (between 1 and 255. The value 0 is forbidden because it represents the end of the string in C/C++) immediately after this code.
static void TCODConsole::setColorControl(TCOD_colctrl_t con, const TCODColor &fore, const TCODColor &back)
void TCOD_console_set_color_control(TCOD_colctrl_t con, TCOD_color_t fore, TCOD_color_t back)
console_set_color_control(con,fore,back)
Not supported directly, use getRGBColorControlString and getColorControlString.
Not supported
Parameter | Description |
---|---|
con | the color control TCOD_COLCTRL_x, 1<=x<=5 |
fore | foreground color when this control is activated |
back | background color when this control is activated |
Example:
// A string with a red over black word, using predefined color control codes
TCODConsole::setColorControl(TCOD_COLCTRL_1,TCODColor::red,TCODColor::black);
TCODConsole::root->print(1,1,"String with a %cred%c word.",TCOD_COLCTRL_1,TCOD_COLCTRL_STOP);
// A string with a red over black word, using generic color control codes
TCODConsole::root->print(1,1,"String with a %c%c%c%c%c%c%c%cred%c word.",
TCOD_COLCTRL_FORE_RGB,255,1,1,TCOD_COLCTRL_BACK_RGB,1,1,1,TCOD_COLCTRL_STOP);
// A string with a red over black word, using generic color control codes
TCODConsole::root->print(1,1,"String with a %c%c%c%c%c%c%c%cred%c word.",
TCOD_COLCTRL_FORE_RGB,255,1,1,TCOD_COLCTRL_BACK_RGB,1,1,1,TCOD_COLCTRL_STOP);
// A string with a red over black word, using predefined color control codes
TCOD_console_set_color_control(TCOD_COLCTRL_1,red,black);
TCOD_console_print(NULL,1,1,"String with a %cred%c word.",TCOD_COLCTRL_1,TCOD_COLCTRL_STOP);
// A string with a red word (over default background color), using generic color control codes
TCOD_console_print(NULL,1,1,"String with a %c%c%c%cred%c word.",
TCOD_COLCTRL_FORE_RGB,255,1,1,TCOD_COLCTRL_STOP);
// A string with a red over black word, using generic color control codes
TCOD_console_print(NULL,1,1,"String with a %c%c%c%c%c%c%c%cred%c word.",
TCOD_COLCTRL_FORE_RGB,255,1,1,TCOD_COLCTRL_BACK_RGB,1,1,1,TCOD_COLCTRL_STOP);
# A string with a red over black word, using predefined color control codes
libtcod.console_set_color_control(libtcod.COLCTRL_1,litbcod.red,litbcod.black)
libtcod.console_print(0,1,1,"String with a %cred%c word."%(libtcod.COLCTRL_1,libtcod.COLCTRL_STOP))
# A string with a red word (over default background color), using generic color control codes
litbcod.console_print(0,1,1,"String with a %c%c%c%cred%c word."%(libtcod.COLCTRL_FORE_RGB,255,1,1,libtcod.COLCTRL_STOP))
# A string with a red over black word, using generic color control codes
libtcod.console_print(0,1,1,"String with a %c%c%c%c%c%c%c%cred%c word."%
(libtcod.COLCTRL_FORE_RGB,255,1,1,libtcod.COLCTRL_BACK_RGB,1,1,1,libtcod.COLCTRL_STOP))
TCODConsole.root.print(1,1,String.Format("String with a {0}red{1} word.",
TCODConsole.getRGBColorControlString(ColorControlForeground,TCODColor.red),
TCODConsole.getColorControlString(ColorControlStop));
Unicode functions
those functions are similar to their ASCII equivalent, but work with unicode strings (wchar_t in C/C++).
Note that unicode is not supported in the python wrapper.
static void TCODConsole::mapStringToFont(const wchar_t *s, int fontCharX, int fontCharY)
void TCOD_console_map_string_to_font_utf(const wchar_t *s, int fontCharX, int fontCharY)
void TCODConsole::print(int x, int y, const wchar_t *fmt, ...)
void TCOD_console_print_utf(TCOD_console_t con,int x, int y, const wchar_t *fmt, ...)
void TCODConsole::printEx(int x, int y, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const wchar_t *fmt, ...)
void TCOD_console_print_ex_utf(TCOD_console_t con,int x, int y, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const wchar_t *fmt, ...)
int TCODConsole::printRect(int x, int y, int w, int h, const wchar_t *fmt, ...)
int TCOD_console_print_rect_utf(TCOD_console_t con,int x, int y, int w, int h, const wchar_t *fmt, ...)
int TCODConsole::printRectEx(int x, int y, int w, int h, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const wchar_t *fmt, ...)
int TCOD_console_print_rect_ex_utf(TCOD_console_t con,int x, int y, int w, int h, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const wchar_t *fmt, ...)
int TCODConsole::getHeightRect(int x, int y, int w, int h, const wchar_t *fmt, ...)
int TCOD_console_get_height_rect_utf(TCOD_console_t con,int x, int y, int w, int h, const wchar_t *fmt, ...)