cgul_line_wrapper.h File Reference

line wrapper More...

#include "cgul_common.h"
#include "cgul_bdf.h"
#include "cgul_exception.h"
#include "cgul_string.h"
#include "cgul_wstring.h"

Include dependency graph for cgul_line_wrapper.h:

This graph shows which files directly or indirectly include this file:

Functions
CGUL_BEGIN_C CGUL_EXPORT void	cgul_line_wrapper__wrap_utf8_at_column (cgul_exception_t *cex, cgul_string_t lines, unsigned int column)
CGUL_EXPORT void	cgul_line_wrapper__wrap_utf32_at_column (cgul_exception_t *cex, cgul_wstring_t wlines, unsigned int column)
CGUL_EXPORT void	cgul_line_wrapper__wrap_utf8_at_width (cgul_exception_t *cex, cgul_string_t lines, cgul_bdf_t bdf, int substitute, unsigned int max_line_width)
CGUL_EXPORT void	cgul_line_wrapper__wrap_utf32_at_width (cgul_exception_t *cex, cgul_wstring_t wlines, cgul_bdf_t bdf, int substitute, unsigned int max_line_width)

Detailed Description

The functions in this file wrap lines based on a certain number of characters per line (which is suitable for formatting output for a terminal) or based on the variable-length spacing between characters in a BDF font loaded by the cgul_bdf class.

Author

Paul Serice

Function Documentation

cgul_line_wrapper__wrap_utf8_at_column()

CGUL_BEGIN_C CGUL_EXPORT void cgul_line_wrapper__wrap_utf8_at_column	(	cgul_exception_t *	cex,
		cgul_string_t	lines,
		unsigned int	column
	)

This function wraps the UTF-8 string lines at column and returns the result in lines. This is used for formatting text destined for the console. It assumes all characters have the same, unspecified width. So the wrapping is based on the maximum number of characters per line.

It is permissible for lines to have embedded new-line characters before calling this method. When an embedded new-line character is encountered, this method will honor it and force the start of a new line.

If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in,out]	lines	lines to wrap
[in]	column	column at which to wrap

Referenced by cgul_line_wrapper_cxx::wrap_utf8_at_column().

cgul_line_wrapper__wrap_utf32_at_column()

CGUL_EXPORT void cgul_line_wrapper__wrap_utf32_at_column	(	cgul_exception_t *	cex,
		cgul_wstring_t	wlines,
		unsigned int	column
	)

This function wraps the UTF-32 string wlines at column and returns the result in wlines. This is used for formatting text destined for the console. It assumes all characters have the same, unspecified width. So the wrapping is based on the maximum number of wide characters per line.

It is permissible for wlines to have embedded new-line wide characters before calling this method. When an embedded new-line wide character is encountered, this method will honor it and force the start of a new line.

If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in,out]	wlines	lines to wrap
[in]	column	column at which to wrap

Referenced by cgul_line_wrapper_cxx::wrap_utf32_at_column().

cgul_line_wrapper__wrap_utf8_at_width()

CGUL_EXPORT void cgul_line_wrapper__wrap_utf8_at_width	(	cgul_exception_t *	cex,
		cgul_string_t	lines,
		cgul_bdf_t	bdf,
		int	substitute,
		unsigned int	max_line_width
	)

This function wraps the UTF-8 string lines at width and returns the result in lines. This is used for formatting text destined to be drawn on a graphical surface. The amount of space each line consumes is calculated using the BDF font bdf by calling cgul_bdf__get_utf8_extents(). Thus, in order for this function to be accurate, your code must draw text as explained in the comments to cgul_bdf__get_utf8_extents() and the value you pass in here for substitute must match.

It is permissible for lines to have embedded new-line characters before calling this method. When an embedded new-line character is encountered, this method will honor it and force the start of a new line.

If substitute is set, this method assumes the code that draws the text will substitute missing glyphs with the default glyph for the font, e.g., an empty box. If substitute is not set, this method will throw an exception if it cannot find the glyph for one of the characters in lines.

If you just need to calculate the width of a string in pixels, you can use cgul_bdf__get_utf8_extents() instead.

If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in,out]	lines	lines to wrap
[in]	bdf	BDF font
[in]	substitute	whether to substitute missing glyphs with the default
[in]	max_line_width	maximum line width before wrapping occurs

Referenced by cgul_line_wrapper_cxx::wrap_utf8_at_width().

cgul_line_wrapper__wrap_utf32_at_width()

CGUL_EXPORT void cgul_line_wrapper__wrap_utf32_at_width	(	cgul_exception_t *	cex,
		cgul_wstring_t	wlines,
		cgul_bdf_t	bdf,
		int	substitute,
		unsigned int	max_line_width
	)

This function wraps the UTF-32 string wlines at width and returns the result in wlines. This is used for formatting text destined to be drawn on a graphical surface. The amount of space each line consumes is calculated using the BDF font bdf by calling cgul_bdf__get_utf32_extents(). Thus, in order for this function to be accurate, your code must draw text as explained in the comments to cgul_bdf__get_utf32_extents() and the value you pass in here for substitute must match.

It is permissible for wlines to have embedded new-line characters before calling this method. When an embedded new-line character is encountered, this method will honor it and force the start of a new line.

If substitute is set, this method assumes the code that draws the text will substitute missing glyphs with the default glyph for the font, e.g., an empty box. If substitute is not set, this method will throw an exception if it cannot find the glyph for one of the characters in lines.

If you just need to calculate the width of a string in pixels, you can use cgul_bdf__get_utf32_extents() instead.

If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in,out]	wlines	lines to wrap
[in]	bdf	BDF font
[in]	substitute	whether to substitute missing glyphs with the default
[in]	max_line_width	maximum line width before wrapping occurs

Referenced by cgul_line_wrapper_cxx::wrap_utf32_at_width().