Printing (Unicode)

Printing functions supporting UTF-8 strings. More...

Classes
struct	TCOD_PrintParamsRGB
	Information about a string to be printed. More...

Typedefs
typedef struct TCOD_PrintParamsRGB	TCOD_PrintParamsRGB
	Information about a string to be printed.

Functions
TCOD_Error	TCOD_console_printf (TCOD_Console *con, int x, int y, const char *fmt,...)
	Format and print a UTF-8 string to a console.
TCOD_Error	TCOD_console_printf_ex (TCOD_Console *con, int x, int y, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const char *fmt,...)
	Format and print a UTF-8 string to a console.
int	TCOD_console_printf_rect (TCOD_Console *con, int x, int y, int w, int h, const char *fmt,...)
	Format and print a UTF-8 string to a console.
int	TCOD_console_printf_rect_ex (TCOD_Console *con, int x, int y, int w, int h, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const char *fmt,...)
	Format and print a UTF-8 string to a console.
TCOD_Error	TCOD_console_printf_frame (TCOD_Console *con, int x, int y, int w, int h, int empty, TCOD_bkgnd_flag_t flag, const char *fmt,...)
	Print a framed and optionally titled region to a console, using default colors and alignment.
int	TCOD_console_get_height_rect_fmt (TCOD_Console *con, int x, int y, int w, int h, const char *fmt,...)
	Return the number of lines that would be printed by this formatted string.
TCOD_Error	TCOD_console_printn (TCOD_Console *console, int x, int y, size_t n, const char *str, const TCOD_ColorRGB *fg, const TCOD_ColorRGB *bg, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment)
	Print a string of a specified length to a console.
int	TCOD_console_printn_rect (TCOD_Console *console, int x, int y, int width, int height, size_t n, const char *str, const TCOD_ColorRGB *fg, const TCOD_ColorRGB *bg, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment)
	Print a string of a specified length in a bounding box to a console.
int	TCOD_console_get_height_rect_n (TCOD_Console *console, int x, int y, int width, int height, size_t n, const char *str)
	Return the height of the word-wrapped text with the given parameters.
int	TCOD_console_get_height_rect_wn (int width, size_t n, const char *str)
	Return the height of the word-wrapped text with the given width.
TCOD_Error	TCOD_console_printn_frame (TCOD_Console *console, int x, int y, int width, int height, size_t n, const char *title, const TCOD_ColorRGB *fg, const TCOD_ColorRGB *bg, TCOD_bkgnd_flag_t flag, bool clear)
TCOD_Error	TCOD_console_vprintf (TCOD_Console *console, int x, int y, const TCOD_color_t *fg, const TCOD_color_t *bg, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const char *fmt, va_list args)
	Print a formatted string using a va_list.
int	TCOD_console_vprintf_rect (TCOD_Console *console, int x, int y, int width, int height, const TCOD_color_t *fg, const TCOD_color_t *bg, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const char *fmt, va_list args)
	Print a formatted string using a va_list within a bounding box.
int	TCOD_printf_rgb (TCOD_Console *console, TCOD_PrintParamsRGB params, const char *fmt,...)
	Prints a formatted string to the console.
int	TCOD_printn_rgb (TCOD_Console *console, TCOD_PrintParamsRGB params, int n, const char *str)
	Prints n-bytes of a string string to the console.
int	TCOD_vprintf_rgb (TCOD_Console *console, TCOD_PrintParamsRGB params, const char *fmt, va_list args)
	Prints a formatted string using va_list.
void	tcod::print (TCOD_Console &console, const std::array< int, 2 > &xy, std::string_view str, std::optional< TCOD_ColorRGB > fg, std::optional< TCOD_ColorRGB > bg, TCOD_alignment_t alignment=TCOD_LEFT, TCOD_bkgnd_flag_t flag=TCOD_BKGND_SET)
	Print a string to a console.
int	tcod::print_rect (TCOD_Console &console, const std::array< int, 4 > &rect, std::string_view str, std::optional< TCOD_ColorRGB > fg, std::optional< TCOD_ColorRGB > bg, TCOD_alignment_t alignment=TCOD_LEFT, TCOD_bkgnd_flag_t flag=TCOD_BKGND_SET)
	Print a string to a console constrained to a bounding box.
int	tcod::get_height_rect (int width, std::string_view str)
	Return the height of the word-wrapped text with the given width.
TCODLIB_BEGIN_IGNORE_DEPRECATIONS void	tcod::print_frame (struct TCOD_Console &console, const std::array< int, 4 > &rect, std::string_view title, const TCOD_ColorRGB *fg, const TCOD_ColorRGB *bg, TCOD_bkgnd_flag_t flag=TCOD_BKGND_SET, bool clear=true)

Detailed Description

Printing functions supporting UTF-8 strings.

Function Documentation

get_height_rect()

int tcod::get_height_rect ( int width, std::string_view str )

inline

Return the height of the word-wrapped text with the given width.

Parameters

width	The maximum width of the bounding region in tiles.
str	The text to print. This string can contain libtcod color codes.

Returns

int The height of the text as if it were printed.

auto console = tcod::Console{80, 50};
int y = console->h; // Start Y at the bottom of this console.
const int width = 6;
y -= tcod::get_height_rect("Long text example", width); // Move y up by the height of this text.
tcod::print(console, {0, y, width, 0}, "Long text example", std::nullopt, std::nullopt);

embed:rst:leading-asterisk 
.. versionadded:: 1.19

print()

void tcod::print ( TCOD_Console & console, const std::array< int, 2 > & xy, std::string_view str, std::optional< TCOD_ColorRGB > fg, std::optional< TCOD_ColorRGB > bg, TCOD_alignment_t alignment = TCOD_LEFT, TCOD_bkgnd_flag_t flag = TCOD_BKGND_SET )

inline

Print a string to a console.

Parameters

console	A reference to a TCOD_Console.
xy	The starting {x, y} position, starting from the upper-left-most tile as zero.
str	The text to print. This string can contain libtcod color codes.
fg	The foreground color. The printed text is set to this color. If std::nullopt then the foreground will be left unchanged, inheriting the previous value of the tile.
bg	The background color. The background tile under the printed text is set to this color. If std::nullopt then the background will be left unchanged.
alignment	The text justification.
flag	The background blending flag.

auto console = tcod::Console{80, 50};
tcod::print(console, {0, 0}, "Hello World", {{255, 255, 255}}, {{0, 0, 0}});

embed:rst:leading-asterisk 
.. versionadded:: 1.19

print_rect()

int tcod::print_rect ( TCOD_Console & console, const std::array< int, 4 > & rect, std::string_view str, std::optional< TCOD_ColorRGB > fg, std::optional< TCOD_ColorRGB > bg, TCOD_alignment_t alignment = TCOD_LEFT, TCOD_bkgnd_flag_t flag = TCOD_BKGND_SET )

inline

Print a string to a console constrained to a bounding box.

Parameters

console	A reference to a TCOD_Console.
rect	An {x, y, width, height} rectangle, starting from the upper-left-most tile as zero. A width or height of zero will leave that axis unconstrained.
str	The text to print. This string can contain libtcod color codes.
fg	The foreground color. The printed text is set to this color. If std::nullopt then the foreground will be left unchanged, inheriting the previous value of the tile.
bg	The background color. The background tile under the printed text is set to this color. If std::nullopt then the background will be left unchanged.
alignment	The text justification.
flag	The background blending flag.

Returns

int The height of the printed output.

auto console = tcod::Console{80, 50};
static constexpr auto TEAL = tcod::ColorRGB{0, 255, 255};
// Print "Hello World" centered along the top row, ignoring the background color.
tcod::print(console, {0, 0, console->w, 1}, "Hello World", TEAL, std::nullopt, TCOD_CENTER);

embed:rst:leading-asterisk 
.. versionadded:: 1.19

TCOD_console_get_height_rect_fmt()

int TCOD_console_get_height_rect_fmt	(	TCOD_Console *	con,
		int	x,
		int	y,
		int	w,
		int	h,
		const char *	fmt,
			... )

Return the number of lines that would be printed by this formatted string.

embed:rst:leading-asterisk 
.. versionadded:: 1.8

.. versionchanged:: 1.16
    Now returns a negative error code on failure.

TCOD_console_get_height_rect_n()

int TCOD_console_get_height_rect_n	(	TCOD_Console *	console,
		int	x,
		int	y,
		int	width,
		int	height,
		size_t	n,
		const char *	str )

Return the height of the word-wrapped text with the given parameters.

Parameters

console	A pointer to a TCOD_Console.
x	The starting X position, starting from the left-most tile as zero.
y	The starting Y position, starting from the upper-most tile as zero.
width	The maximum width of the bounding region in tiles.
height	The maximum height of the bounding region in tiles.
n	The length of the string buffer str[n] in bytes.
str	The text to print. This string can contain libtcod color codes.

Returns

int The height of the word-wrapped text as if it were printed, or a negative error code on failure.

embed:rst:leading-asterisk 
.. versionadded:: 1.19

TCOD_console_get_height_rect_wn()

int TCOD_console_get_height_rect_wn	(	int	width,
		size_t	n,
		const char *	str )

Return the height of the word-wrapped text with the given width.

Parameters

width	The maximum width of the bounding region in tiles.
n	The length of the string buffer str[n] in bytes.
str	The text to print. This string can contain libtcod color codes.

Returns

int The height of the word-wrapped text as if it were printed, or a negative error code on failure.

embed:rst:leading-asterisk 
.. versionadded:: 1.19

TCOD_console_printf()

TCOD_Error TCOD_console_printf	(	TCOD_Console *	con,
		int	x,
		int	y,
		const char *	fmt,
			... )

Format and print a UTF-8 string to a console.

embed:rst:leading-asterisk 
.. versionadded:: 1.8

.. versionchanged:: 1.16
    Now returns a negative error code on failure.

TCOD_console_printf_ex()

TCOD_Error TCOD_console_printf_ex	(	TCOD_Console *	con,
		int	x,
		int	y,
		TCOD_bkgnd_flag_t	flag,
		TCOD_alignment_t	alignment,
		const char *	fmt,
			... )

Format and print a UTF-8 string to a console.

embed:rst:leading-asterisk 
.. versionadded:: 1.8

.. versionchanged:: 1.16
    Now returns a negative error code on failure.

TCOD_console_printf_frame()

TCOD_Error TCOD_console_printf_frame	(	TCOD_Console *	con,
		int	x,
		int	y,
		int	w,
		int	h,
		int	empty,
		TCOD_bkgnd_flag_t	flag,
		const char *	fmt,
			... )

Print a framed and optionally titled region to a console, using default colors and alignment.

This function uses Unicode box-drawing characters and a UTF-8 formatted string.

embed:rst:leading-asterisk 
.. versionadded:: 1.8

.. versionchanged:: 1.16
    Now returns a negative error code on failure.

TCOD_console_printf_rect()

int TCOD_console_printf_rect	(	TCOD_Console *	con,
		int	x,
		int	y,
		int	w,
		int	h,
		const char *	fmt,
			... )

Format and print a UTF-8 string to a console.

embed:rst:leading-asterisk 
.. versionadded:: 1.8

.. versionchanged:: 1.16
    Now returns a negative error code on failure.

TCOD_console_printf_rect_ex()

int TCOD_console_printf_rect_ex	(	TCOD_Console *	con,
		int	x,
		int	y,
		int	w,
		int	h,
		TCOD_bkgnd_flag_t	flag,
		TCOD_alignment_t	alignment,
		const char *	fmt,
			... )

Format and print a UTF-8 string to a console.

embed:rst:leading-asterisk 
.. versionadded:: 1.8

.. versionchanged:: 1.16
    Now returns a negative error code on failure.

TCOD_console_printn()

TCOD_Error TCOD_console_printn	(	TCOD_Console *	console,
		int	x,
		int	y,
		size_t	n,
		const char *	str,
		const TCOD_ColorRGB *	fg,
		const TCOD_ColorRGB *	bg,
		TCOD_bkgnd_flag_t	flag,
		TCOD_alignment_t	alignment )

Print a string of a specified length to a console.

Parameters

console	A pointer to a TCOD_Console.
x	The starting X position, starting from the left-most tile as zero.
y	The starting Y position, starting from the upper-most tile as zero.
n	The length of the string buffer str[n] in bytes.
str	The text to print. This string can contain libtcod color codes.
fg	The foreground color. The printed text is set to this color. If NULL then the foreground will be left unchanged, inheriting the previous value of the tile.
bg	The background color. The background tile under the printed text is set to this color. If NULL then the background will be left unchanged.
flag	The background blending flag. If unsure then use TCOD_BKGND_SET.
alignment	The text justification. This is one of TCOD_alignment_t and is normally TCOD_LEFT.

Returns

TCOD_Error Any problems such as malformed UTF-8 will return a negative error code.

embed:rst:leading-asterisk 
.. versionadded:: 1.19

TCOD_console_printn_rect()

int TCOD_console_printn_rect	(	TCOD_Console *	console,
		int	x,
		int	y,
		int	width,
		int	height,
		size_t	n,
		const char *	str,
		const TCOD_ColorRGB *	fg,
		const TCOD_ColorRGB *	bg,
		TCOD_bkgnd_flag_t	flag,
		TCOD_alignment_t	alignment )

Print a string of a specified length in a bounding box to a console.

Parameters

console	A pointer to a TCOD_Console.
x	The starting X position, starting from the left-most tile as zero.
y	The starting Y position, starting from the upper-most tile as zero.
width	The maximum width of the bounding region in tiles.
height	The maximum height of the bounding region in tiles.
n	The length of the string buffer str[n] in bytes.
str	The text to print. This string can contain libtcod color codes.
fg	The foreground color. The printed text is set to this color. If NULL then the foreground will be left unchanged, inheriting the previous value of the tile.
bg	The background color. The background tile under the printed text is set to this color. If NULL then the background will be left unchanged.
flag	The background blending flag. If unsure then use TCOD_BKGND_SET.
alignment	The text justification. This is one of TCOD_alignment_t and is normally TCOD_LEFT.

Returns

int The height of the printed text, or a negative error code on failure.

embed:rst:leading-asterisk 
.. versionadded:: 1.19

TCOD_console_vprintf()

TCOD_Error TCOD_console_vprintf	(	TCOD_Console *	console,
		int	x,
		int	y,
		const TCOD_color_t *	fg,
		const TCOD_color_t *	bg,
		TCOD_bkgnd_flag_t	flag,
		TCOD_alignment_t	alignment,
		const char *	fmt,
		va_list	args )

Print a formatted string using a va_list.

Parameters

console	A pointer to a TCOD_Console.
x	The starting X position, starting from the left-most tile as zero.
y	The starting Y position, starting from the upper-most tile as zero.
fg	The foreground color. The printed text is set to this color. If NULL then the foreground will be left unchanged, inheriting the previous value of the tile.
bg	The background color. The background tile under the printed text is set to this color. If NULL then the background will be left unchanged.
flag	The background blending flag. If unsure then use TCOD_BKGND_SET.
alignment	The text justification. This is one of TCOD_alignment_t and is normally TCOD_LEFT.
fmt	The format string for a vprintf-like function.
args	The arguments for the formatted string.

Returns

TCOD_Error Any problems such as malformed UTF-8 will return a negative error code.

embed:rst:leading-asterisk 
.. versionadded:: 1.19

TCOD_console_vprintf_rect()

int TCOD_console_vprintf_rect	(	TCOD_Console *	console,
		int	x,
		int	y,
		int	width,
		int	height,
		const TCOD_color_t *	fg,
		const TCOD_color_t *	bg,
		TCOD_bkgnd_flag_t	flag,
		TCOD_alignment_t	alignment,
		const char *	fmt,
		va_list	args )

Print a formatted string using a va_list within a bounding box.

Parameters

console	A pointer to a TCOD_Console.
x	The starting X position, starting from the left-most tile as zero.
y	The starting Y position, starting from the upper-most tile as zero.
width	The maximum width of the bounding region in tiles.
height	The maximum height of the bounding region in tiles.
fg	The foreground color. The printed text is set to this color. If NULL then the foreground will be left unchanged, inheriting the previous value of the tile.
bg	The background color. The background tile under the printed text is set to this color. If NULL then the background will be left unchanged.
flag	The background blending flag. If unsure then use TCOD_BKGND_SET.
alignment	The text justification. This is one of TCOD_alignment_t and is normally TCOD_LEFT.
fmt	The format string for a vprintf-like function.
args	The arguments for the formatted string.

Returns

int The height of the printed text, or a negative error code on failures.

embed:rst:leading-asterisk 
.. versionadded:: 1.19

TCOD_printf_rgb()

int TCOD_printf_rgb	(	TCOD_Console *	console,
		TCOD_PrintParamsRGB	params,
		const char *	fmt,
			... )

Prints a formatted string to the console.

Parameters

console	A pointer to a TCOD_Console.
params	Information about how the string should be printed
fmt	The format string for a vprintf-like function.
args	The arguments for the formatted string.

Returns

An error code if less than 0

embed:rst:leading-asterisk 
.. versionadded:: 1.23

TCOD_printn_rgb()

int TCOD_printn_rgb	(	TCOD_Console *	console,
		TCOD_PrintParamsRGB	params,
		int	n,
		const char *	str )

Prints n-bytes of a string string to the console.

Parameters

console	A pointer to a TCOD_Console.
params	Information about how the string should be printed
str	The string to be read from.
n	Length of string in bytes

Returns

An error code if less than 0

embed:rst:leading-asterisk 
.. versionadded:: 1.23

TCOD_vprintf_rgb()

int TCOD_vprintf_rgb	(	TCOD_Console *	console,
		TCOD_PrintParamsRGB	params,
		const char *	fmt,
		va_list	args )

Prints a formatted string using va_list.

Parameters

console	A pointer to a TCOD_Console.
params	Information about how the string should be printed
fmt	The format string for a vprintf-like function
args	The arguments for the format string

Returns

An error code if less than 0

embed:rst:leading-asterisk 
.. versionadded:: 1.23