Graphical text output. More...

Classes
struct	floating_label_context
	structure which will hide all current floating labels, and cause floating labels instantiated after it is created to be displayed More...

class	floating_label

class	attribute_list
	Helper class to encapsulate the management of a PangoAttrList. More...

struct	error

struct	manager

struct	subset_descriptor

class	p_font
	Small helper class to make sure the pango font object is destroyed properly. More...

struct	inverse_table

class	pango_text
	Text class. More...

Enumerations
enum	ALIGN { LEFT_ALIGN , CENTER_ALIGN , RIGHT_ALIGN }

enum	LABEL_SCROLL_MODE { ANCHOR_LABEL_SCREEN , ANCHOR_LABEL_MAP }

enum class	family_class { sans_serif , monospace , script }

Functions
int	add_floating_label (const floating_label &flabel)
	add a label floating on the screen above everything else. More...

void	move_floating_label (int handle, double xmove, double ymove)
	moves the floating label given by 'handle' by (xmove,ymove) More...

void	scroll_floating_labels (double xmove, double ymove)
	moves all floating labels that have 'scroll_mode' set to ANCHOR_LABEL_MAP More...

void	remove_floating_label (int handle, const std::chrono::milliseconds &fadeout=std::chrono::milliseconds{0})
	removes the floating label given by 'handle' from the screen More...

void	show_floating_label (int handle, bool show)
	hides or shows a floating label More...

rect	get_floating_label_rect (int handle)

void	draw_floating_labels ()

void	update_floating_labels ()

void	add_attribute_size (attribute_list &list, unsigned offset_start, unsigned offset_end, int size)
	Add Pango font size attribute to a specific portion of text. More...

void	add_attribute_weight (attribute_list &list, unsigned offset_start, unsigned offset_end, PangoWeight weight)
	Add Pango font weight attribute to a specific portion of text. More...

void	add_attribute_style (attribute_list &list, unsigned offset_start, unsigned offset_end, PangoStyle style)
	Add Pango font style attribute to a specific portion of text, used to set italic/oblique text. More...

void	add_attribute_underline (attribute_list &list, unsigned offset_start, unsigned offset_end, PangoUnderline underline)
	Add Pango underline attribute to a specific portion of text. More...

void	add_attribute_fg_color (attribute_list &list, unsigned offset_start, unsigned offset_end, const color_t &color)
	Add Pango fg color attribute to a specific portion of text. More...

void	add_attribute_bg_color (attribute_list &list, unsigned offset_start, unsigned offset_end, const color_t &color)
	Mark a specific portion of text for highlighting. More...

void	add_attribute_font_family (attribute_list &list, unsigned offset_start, unsigned offset_end, font::family_class family)
	Add Pango font family attribute to a specific portion of text. More...

void	add_attribute_line_height (attribute_list &list, unsigned offset_start, unsigned offset_end, const double factor)
	Add Pango line height attribute to a specific portion of text. More...

void	add_attribute_image_shape (attribute_list &list, unsigned offset_start, unsigned offset_end, const std::string &image_path)
	Add Pango shape attribute to a specific portion of text. More...

int	relative_size (int size)

bool	load_font_config ()

const t_string &	get_font_families (family_class fclass)
	Returns the currently defined fonts. More...

family_class	decode_family_class (const std::string &str)

std::string	escape_text (std::string_view text)
	Escapes the pango markup characters in a text. More...

std::string	semi_escape_text (std::string_view text)

bool	looks_like_url (std::string_view str)

std::string	format_as_link (const std::string &link, color_t color)

texture	pango_render_text (const std::string &text, int size, const color_t &color, font::pango_text::FONT_STYLE style=font::pango_text::STYLE_NORMAL, bool use_markup=false, int max_width=-1)
	Returns a SDL texture containing the rendered text. More...

std::pair< int, int >	pango_line_size (const std::string &line, int font_size, font::pango_text::FONT_STYLE font_style=font::pango_text::STYLE_NORMAL)
	Determine the width and height of a line of text given a certain font size. More...

std::string	pango_word_wrap (const std::string &unwrapped_text, int font_size, int max_width, int max_height=-1, int max_lines=-1, bool partial_line=false)
	Uses Pango to word wrap text. More...

rect	pango_draw_text (bool actually_draw, const rect &area, int size, const color_t &color, const std::string &text, int x, int y)
	Draws text on the screen. More...

color_t	string_to_color (const std::string &color_str)
	Return the color the string represents. More...

static void	unpremultiply (uint8_t &value, const unsigned div)

static void	from_cairo_format (uint32_t &c)
	Converts from cairo-format ARGB32 premultiplied alpha to plain alpha. More...

pango_text &	get_text_renderer ()
	Returns a reference to a static pango_text object. More...

int	get_max_height (unsigned size, font::family_class fclass=font::family_class::sans_serif, pango_text::FONT_STYLE style=pango_text::STYLE_NORMAL)
	Returns the maximum glyph height of a font, in pixels. More...

constexpr float	get_line_spacing_factor ()

Variables
const int	SIZE_NORMAL = 17

const int	SIZE_TINY = 13 * (SIZE_NORMAL / 17)

const int	SIZE_SMALL = 15 * (SIZE_NORMAL / 17)

const int	SIZE_BUTTON = 16 * (SIZE_NORMAL / 17)

const int	SIZE_BUTTON_SMALL = 14 * (SIZE_NORMAL / 17)

const int	SIZE_15 = 15 * (SIZE_NORMAL / 17)

const int	SIZE_PLUS = 18 * (SIZE_NORMAL / 17)

const int	SIZE_LARGE = 20 * (SIZE_NORMAL / 17)

const int	SIZE_TITLE = 22 * (SIZE_NORMAL / 17)

const int	SIZE_FLOAT_LABEL = 24 * (SIZE_NORMAL / 17)

const int	SIZE_XLARGE = 36 * (SIZE_NORMAL / 17)

const std::size_t	max_text_line_width = 4096

const std::string	ellipsis = "..."

const std::string	nbsp = " "

const std::string	unicode_minus = "-"

const std::string	unicode_en_dash = "–"

const std::string	unicode_em_dash = "—"

const std::string	unicode_figure_dash = "‒"

const std::string	unicode_multiplication_sign = "×"

const std::string	unicode_bullet = "•"

const std::string	weapon_numbers_sep = "×"

const std::string	weapon_details_sep = "–"

const color_t	NORMAL_COLOR {221, 221, 221}

const color_t	GRAY_COLOR {136, 136, 136}

const color_t	GOOD_COLOR {0 , 181, 26 }

const color_t	BAD_COLOR {255, 0 , 0 }

const color_t	YELLOW_COLOR {255, 255, 0 }

const color_t	TITLE_COLOR {186, 172, 125}

const color_t	LABEL_COLOR {107, 140, 255}

const color_t	INACTIVE_COLOR {150, 150, 150}

const color_t	weapon_color {245, 230, 193}

const color_t	good_dmg_color {130, 240, 50 }

const color_t	bad_dmg_color {250, 140, 80 }

const color_t	weapon_details_color {196, 176, 147}

const color_t	unit_type_color {245, 230, 193}

static constexpr inverse_table	inverse_table_

Detailed Description

Graphical text output.

This module is used to display and measure text. Text can optionally contain special characters, which may change specified display properties such as colour or font size. If special characters are turned on, they can be escaped, C-style, using backslashes.

Enumeration Type Documentation

◆ ALIGN

enum font::ALIGN

Enumerator
LEFT_ALIGN
CENTER_ALIGN
RIGHT_ALIGN

Definition at line 38 of file floating_label.hpp.

◆ family_class

enum font::family_class

strong

Enumerator
sans_serif
monospace
script

Definition at line 23 of file font_options.hpp.

◆ LABEL_SCROLL_MODE

enum font::LABEL_SCROLL_MODE

Enumerator
ANCHOR_LABEL_SCREEN
ANCHOR_LABEL_MAP

Definition at line 40 of file floating_label.hpp.

Function Documentation

◆ add_attribute_bg_color()

void font::add_attribute_bg_color	(	attribute_list &	list,
		unsigned	offset_start,
		unsigned	offset_end,
		const color_t &	color
	)

Mark a specific portion of text for highlighting.

Used for selection box. BGColor is set in set_text(), this just marks the area to be colored. Markup not used because the user may enter their own markup or special characters

Parameters

list	The attribute list to which to append this attribute.
offset_start	Byte index of the cursor where selection/highlight starts
offset_end	Byte index of the cursor where selection/highlight ends
color	Highlight/Background color

Definition at line 135 of file attributes.cpp.

References DBG_GUI_D, and color_t::to_pango_format().

Referenced by gui2::text_shape::draw(), and gui2::text_box_base::set_highlight_area().

◆ add_attribute_fg_color()

void font::add_attribute_fg_color	(	attribute_list &	list,
		unsigned	offset_start,
		unsigned	offset_end,
		const color_t &	color
	)

Add Pango fg color attribute to a specific portion of text.

This changes the foreground color of the corresponding part of the text.

Parameters

list	The attribute list to which to append this attribute.
offset_start	Byte index of the cursor where color change starts
offset_end	Byte index of the cursor where color change ends
color	Foreground color

Definition at line 119 of file attributes.cpp.

References DBG_GUI_D, and color_t::to_pango_format().

◆ add_attribute_font_family()

void font::add_attribute_font_family	(	attribute_list &	list,
		unsigned	offset_start,
		unsigned	offset_end,
		font::family_class	family
	)

Add Pango font family attribute to a specific portion of text.

This changes the font family of the corresponding part of the text.

Parameters

list	The attribute list to which to append this attribute.
offset_start	Byte index of the cursor where size change starts
offset_end	Byte index of the cursor where size change ends
family	The font family

Definition at line 150 of file attributes.cpp.

References t_string::c_str(), DBG_GUI_D, and get_font_families().

◆ add_attribute_image_shape()

void font::add_attribute_image_shape	(	attribute_list &	list,
		unsigned	offset_start,
		unsigned	offset_end,
		const std::string &	image_path
	)

Add Pango shape attribute to a specific portion of text.

This replaces the text within the start and end offsets with an inline image. The caller should ensure that the portion of text between the given offset range is filled with dummy characters, such as

Parameters

list	The attribute list to which to append this attribute.
offset_start	Byte index of the cursor where size change starts
offset_end	Byte index of the cursor where size change ends
image_path	Path to the image to be shown inline

Definition at line 180 of file attributes.cpp.

References cairo::create_surface(), DBG_GUI_D, video::get_pixel_scale(), image::get_surface(), xbrz::scale(), and surf.

◆ add_attribute_line_height()

void font::add_attribute_line_height	(	attribute_list &	list,
		unsigned	offset_start,
		unsigned	offset_end,
		const double	factor
	)

Add Pango line height attribute to a specific portion of text.

This changes the line height of the corresponding part of the text.

Parameters

list	The attribute list to which to append this attribute.
offset_start	Byte index of the cursor where size change starts
offset_end	Byte index of the cursor where size change ends
factor	The line height factor, i.e., `new_line_height/old_line_height`

Definition at line 166 of file attributes.cpp.

References DBG_GUI_D.

◆ add_attribute_size()

void font::add_attribute_size	(	attribute_list &	list,
		unsigned	offset_start,
		unsigned	offset_end,
		int	size
	)

Add Pango font size attribute to a specific portion of text.

This changes the font size of the corresponding part of the text.

Parameters

list	The attribute list to which to append this attribute.
offset_start	Byte index of the cursor where size change starts
offset_end	Byte index of the cursor where size change ends
size	Font size

Definition at line 64 of file attributes.cpp.

References DBG_GUI_D, prefs::font_scaled(), prefs::get(), video::get_pixel_scale(), and utf8::size().

◆ add_attribute_style()

void font::add_attribute_style	(	attribute_list &	list,
		unsigned	offset_start,
		unsigned	offset_end,
		PangoStyle	style
	)

Add Pango font style attribute to a specific portion of text, used to set italic/oblique text.

Parameters

list	The attribute list to which to append this attribute.
offset_start	Byte index of the cursor where font style change starts
offset_end	Byte index of the cursor where font style change ends
style	Pango font style (normal/italic/oblique)

Definition at line 93 of file attributes.cpp.

References DBG_GUI_D.

◆ add_attribute_underline()

void font::add_attribute_underline	(	attribute_list &	list,
		unsigned	offset_start,
		unsigned	offset_end,
		PangoUnderline	underline
	)

Add Pango underline attribute to a specific portion of text.

This adds an underline to the corresponding part of the text.

Parameters

list	The attribute list to which to append this attribute.
offset_start	Byte index of the cursor where underline starts
offset_end	Byte index of the cursor where underline change ends
underline	Pango underline style

Definition at line 106 of file attributes.cpp.

References DBG_GUI_D.

◆ add_attribute_weight()

void font::add_attribute_weight	(	attribute_list &	list,
		unsigned	offset_start,
		unsigned	offset_end,
		PangoWeight	weight
	)

Add Pango font weight attribute to a specific portion of text.

This changes the font weight of the corresponding part of the text.

Parameters

list	The attribute list to which to append this attribute.
offset_start	Byte index of the cursor where font weight change starts
offset_end	Byte index of the cursor where font weight change ends
weight	Pango font weight

Definition at line 80 of file attributes.cpp.

References DBG_GUI_D.

◆ add_floating_label()

int font::add_floating_label ( const floating_label & flabel )

add a label floating on the screen above everything else.

Returns: a handle to the label which can be used with other label functions

Definition at line 266 of file floating_label.cpp.

Referenced by display_chat_manager::add_chat_message(), display::announce(), game_display::float_label(), game_lua_kernel::intf_set_floating_label(), terrain_label::recalculate(), display::set_diagnostic(), editor::editor_display::set_help_string(), editor::editor_display::set_status(), and gui::floating_textbox::update_location().

◆ decode_family_class()

family_class font::decode_family_class ( const std::string & str )

inline

Definition at line 30 of file font_options.hpp.

References monospace, sans_serif, and script.

◆ draw_floating_labels()

void font::draw_floating_labels ( )

Definition at line 363 of file floating_label.cpp.

References label.

Referenced by display::expose().

◆ escape_text()

std::string font::escape_text ( std::string_view text )

inline

Escapes the pango markup characters in a text.

The markups escaped are the ones used in the pango markup. The special characters are:

<>'"&

The escaping is the same as for HTML.

Parameters

text	The text to escape.

Returns: The escaped text.

Definition at line 33 of file escape.hpp.

References c.

Referenced by about::credits_group::about_group::about_group(), gui2::chatbox::add_active_window_message(), gui2::chatbox::add_active_window_whisper(), gui2::chatbox::add_chat_message(), gui2::dialogs::lua_interpreter::lua_model::add_dialog_message(), gui2::chatbox::add_room_window_message(), gui2::chatbox::add_whisper_window_whisper(), addons_client::delete_remote_addon(), addon_info::display_title(), addons_client::do_check_before_overwriting_addon(), addons_client::download_addon(), addons_client::install_addon(), addons_client::is_error_response(), gui2::dialogs::lua_interpreter::lua_model::lua_model(), gui2::dialogs::formula_debugger::pre_show(), gui2::dialogs::chat_log::model::stream_log(), unit_name(), and addons_client::upload_addon().

◆ format_as_link()

std::string font::format_as_link	(	const std::string &	link,
		color_t	color
	)

inline

Definition at line 33 of file hyperlink.hpp.

References color_t::to_hex_string().

Referenced by font::pango_text::format_links().

◆ from_cairo_format()

static void font::from_cairo_format ( uint32_t & c )

static

Converts from cairo-format ARGB32 premultiplied alpha to plain alpha.

Parameters

c	a uint32 representing the color

Definition at line 694 of file text.cpp.

References b, c, g, inverse_table_, and unpremultiply().

Referenced by font::pango_text::create_surface().

◆ get_floating_label_rect()

rect font::get_floating_label_rect ( int handle )

Definition at line 324 of file floating_label.cpp.

References i, and utf8::size().

Referenced by display_chat_manager::add_chat_message(), editor::editor_display::layout(), display_chat_manager::prune_chat_messages(), editor::editor_display::set_help_string(), editor::editor_display::set_status(), and gui::floating_textbox::update_location().

◆ get_font_families()

const t_string & font::get_font_families ( family_class fclass )

Returns the currently defined fonts.

Definition at line 93 of file font_config.cpp.

References monospace, and script.

Referenced by add_attribute_font_family(), font::pango_text::calculate_size(), and font::pango_text::get_max_glyph_height().

◆ get_line_spacing_factor()

constexpr float font::get_line_spacing_factor ( )

constexpr

Definition at line 570 of file text.hpp.

Referenced by gui2::rich_label::add_link(), gui2::rich_label::default_text_config(), gui2::multiline_text::handle_mouse_selection(), and font::pango_text::pango_text().

◆ get_max_height()

int font::get_max_height	(	unsigned	size,
		font::family_class	fclass = `font::family_class::sans_serif`,
		pango_text::FONT_STYLE	style = `pango_text::STYLE_NORMAL`
	)

Returns the maximum glyph height of a font, in pixels.

Parameters

size	Desired font size in pixels.
fclass	Font family to use for measurement.
style	Font style to select the correct variant for measurement.

Returns: The height of the tallest possible glyph for the selected font. More specifically, the result is the sum of the maximum ascent and descent lengths.

Definition at line 966 of file text.cpp.

References font::pango_text::get_max_glyph_height(), get_text_renderer(), font::pango_text::set_family_class(), font::pango_text::set_font_size(), font::pango_text::set_font_style(), and utf8::size().

Referenced by gui2::rich_label::add_link(), gui::textbox::add_text_line(), gui::textbox::textbox(), gui2::combobox::update_offsets(), gui2::multiline_text::update_offsets(), and gui2::text_box::update_offsets().

◆ get_text_renderer()

pango_text & font::get_text_renderer ( )

Returns a reference to a static pango_text object.

Since the class is essentially a render pipeline, there's no need for individual areas of the game to own their own renderers. Not to mention it isn't a trivial class; constructing one is likely to be expensive.

Definition at line 960 of file text.cpp.

Referenced by font::floating_label::create_texture(), gui2::text_shape::draw(), display::draw_hex(), display::draw_label(), display::draw_report(), display::draw_text_in_hex(), get_max_height(), gui2::rich_label::get_offset_from_xy(), and gui2::rich_label::get_xy_from_offset().

◆ load_font_config()

bool font::load_font_config ( )

Definition at line 78 of file font_config.cpp.

References filesystem::get_wml_location(), config::mandatory_child(), preprocess_file(), and io::read().

Referenced by game_launcher::change_language(), do_gameloop(), and test_utils::game_config_manager::game_config_manager().

◆ looks_like_url()

bool font::looks_like_url ( std::string_view str )

inline

Definition at line 28 of file hyperlink.hpp.

Referenced by font::pango_text::format_links(), and font::pango_text::get_link().

◆ move_floating_label()

void font::move_floating_label	(	int	handle,
		double	xmove,
		double	ymove
	)

moves the floating label given by 'handle' by (xmove,ymove)

Definition at line 278 of file floating_label.cpp.

References i.

Referenced by game_lua_kernel::intf_move_floating_label(), editor::editor_display::layout(), display_chat_manager::prune_chat_messages(), editor::editor_display::set_help_string(), and editor::editor_display::set_status().

◆ pango_draw_text()

rect font::pango_draw_text	(	bool	actually_draw,
		const rect &	area,
		int	size,
		const color_t &	color,
		const std::string &	text,
		int	x,
		int	y
	)

Draws text on the screen.

The text will be clipped to area. If the text runs outside of area horizontally, an ellipsis will be displayed at the end of it. If area is empty, the text will not be clipped.

A bounding rectangle of the text is returned. If actually_draw is true the text will also be drawn to the screen. Otherwise only the bounding rectangle is returned.

Definition at line 107 of file sdl_ttf_compat.cpp.

References draw::blit(), rect::empty(), sans_serif, utf8::size(), font::pango_text::STYLE_NORMAL, and t.

Referenced by gui::button::calculate_size(), gui::button::draw_contents(), and location_palette_item::draw_contents().

◆ pango_line_size()

std::pair< int, int > font::pango_line_size	(	const std::string &	line,
		int	font_size,
		font::pango_text::FONT_STYLE	font_style
	)

Determine the width and height of a line of text given a certain font size.

Definition at line 59 of file sdl_ttf_compat.cpp.

References draw::line(), s, and sans_serif.

Referenced by gui::textbox::add_text_line(), and editor::editor_display::set_help_string().

◆ pango_render_text()

texture font::pango_render_text	(	const std::string &	text,
		int	size,
		const color_t &	color,
		font::pango_text::FONT_STYLE	style,
		bool	use_markup,
		int	max_width
	)