libtcoddocumentation

2.2.3. String drawing 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)

ParameterDescription
conin the C and Python versions, the offscreen console handler or NULL for the root console
flagthis 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)

ParameterDescription
conin 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)

ParameterDescription
conin the C and Python versions, the offscreen console handler or NULL for the root console
alignmentdefines 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)

ParameterDescription
conin 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)

ParameterDescription
conin the C and Python versions, the offscreen console handler or NULL for the root console
x,ycoordinate 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
fmtprintf-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)

ParameterDescription
conin the C and Python versions, the offscreen console handler or NULL for the root console
x,ycoordinate 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
flagthis flag defines how the cell's background color is modified. See TCOD_bkgnd_flag_t
alignmentdefines how the strings are printed on screen.
fmtprintf-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)

ParameterDescription
conin the C and Python versions, the offscreen console handler or NULL for the root console
x,ycoordinate 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,hsize of the rectangle
x <= x+w < console width
y <= y+h < console height
fmtprintf-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)

ParameterDescription
conin the C and Python versions, the offscreen console handler or NULL for the root console
x,ycoordinate 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,hsize of the rectangle
x <= x+w < console width
y <= y+h < console height
flagthis flag defines how the cell's background color is modified. See TCOD_bkgnd_flag_t
alignmentdefines how the strings are printed on screen.
fmtprintf-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)

ParameterDescription
conin the C and Python versions, the offscreen console handler or NULL for the root console
x,ycoordinate of the rectangle upper-left corner in the console
w,hsize of the rectangle
x <= x+w < console width
y <= y+h < console height
fmtprintf-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)

ParameterDescription
conthe color control TCOD_COLCTRL_x, 1<=x<=5
foreforeground color when this control is activated
backbackground 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))


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, ...)