The Battle for Wesnoth  1.13.10+dev
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
Public Types | Public Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | List of all members
font::pango_text Class Reference

Text class. More...

#include <text.hpp>

Public Types

enum  FONT_STYLE {
  STYLE_NORMAL = 0, STYLE_BOLD = 1, STYLE_ITALIC = 2, STYLE_UNDERLINE = 4,
  STYLE_LIGHT = 8
}
 

Public Member Functions

 pango_text ()
 
 pango_text (const pango_text &)=delete
 
pango_textoperator= (const pango_text &)=delete
 
surfacerender ()
 Returns the rendered text. More...
 
int get_width () const
 Returns the width needed for the text. More...
 
int get_height () const
 Returns the height needed for the text. More...
 
point get_size () const
 Returns the pixel size needed for the text. More...
 
bool is_truncated () const
 Has the text been truncated? This happens if it exceeds max width or height. More...
 
unsigned insert_text (const unsigned offset, const std::string &text)
 Inserts UTF-8 text. More...
 
bool insert_unicode (const unsigned offset, ucs4::char_t unicode)
 Inserts a unicode char. More...
 
unsigned insert_unicode (const unsigned offset, const ucs4::string &unicode)
 Inserts unicode text. More...
 
point get_cursor_position (const unsigned column, const unsigned line=0) const
 Gets the location for the cursor. More...
 
std::string get_token (const point &position, const char *delimiters=" \n\r\t") const
 Gets the largest collection of characters, including the token at position, and not including any characters from the delimiters set. More...
 
std::string get_link (const point &position) const
 Checks if position points to a character in a link in the text, returns it if so, empty string otherwise. More...
 
point get_column_line (const point &position) const
 Gets the column of line of the character at the position. More...
 
size_t get_length () const
 Gets the length of the text in bytes. More...
 
bool set_text (const std::string &text, const bool markedup)
 Sets the text to render. More...
 
const std::string & text () const
 
pango_textset_family_class (font::family_class fclass)
 
pango_textset_font_size (const unsigned font_size)
 
pango_textset_font_style (const FONT_STYLE font_style)
 
pango_textset_foreground_color (const color_t &color)
 
pango_textset_maximum_width (int width)
 
pango_textset_characters_per_line (const unsigned characters_per_line)
 
pango_textset_maximum_height (int height, bool multiline)
 
pango_textset_ellipse_mode (const PangoEllipsizeMode ellipse_mode)
 
pango_textset_alignment (const PangoAlignment alignment)
 
pango_textset_maximum_length (const size_t maximum_length)
 
bool link_aware () const
 
pango_textset_link_aware (bool b)
 
pango_textset_link_color (const color_t &color)
 

Private Member Functions

void recalculate (const bool force=false) const
 Recalculates the text layout. More...
 
PangoRectangle calculate_size (PangoLayout &layout) const
 Calculates surface size. More...
 
void rerender (const bool force=false)
 Renders the text. More...
 
void render (PangoLayout &layout, const PangoRectangle &rect, const size_t surface_buffer_offset, const unsigned stride)
 
void create_surface_buffer (const size_t size) const
 Creates a new buffer. More...
 
bool set_markup (utils::string_view text, PangoLayout &layout)
 Sets the markup'ed text. More...
 
bool validate_markup (utils::string_view text, char **raw_text, std::string &semi_escaped) const
 
void split_surface ()
 Splits the text to two Cairo surfaces. More...
 
bool is_surface_split () const
 
std::vector< std::string > find_links (utils::string_view text) const
 
void format_links (std::string &text, const std::vector< std::string > &links) const
 

Static Private Member Functions

static void copy_layout_properties (PangoLayout &src, PangoLayout &dst)
 

Private Attributes

std::unique_ptr< PangoContext,
std::function< void(void *)> > 
context_
 
std::unique_ptr< PangoLayout,
std::function< void(void *)> > 
layout_
 
PangoRectangle rect_
 
std::vector< std::unique_ptr
< PangoLayout, std::function
< void(void *)> > > 
sublayouts_
 
surface surface_
 The SDL surface to render upon used as a cache. More...
 
std::string text_
 The text to draw (stored as UTF-8). More...
 
bool markedup_text_
 Does the text contain pango markup? If different render routines must be used. More...
 
bool link_aware_
 Are hyperlinks in the text marked-up, and will get_link return them. More...
 
color_t link_color_
 The color to render links in. More...
 
font::family_class font_class_
 The font family class used. More...
 
unsigned font_size_
 The font size to draw. More...
 
FONT_STYLE font_style_
 The style of the font, this is an orred mask of the font flags. More...
 
color_t foreground_color_
 The foreground color. More...
 
int maximum_width_
 The maximum width of the text. More...
 
unsigned characters_per_line_
 The number of characters per line. More...
 
int maximum_height_
 The maximum height of the text. More...
 
PangoEllipsizeMode ellipse_mode_
 The way too long text is shown depends on this mode. More...
 
PangoAlignment alignment_
 The alignment of the text. More...
 
size_t maximum_length_
 The maximum length of the text. More...
 
bool calculation_dirty_
 The text has two dirty states: More...
 
size_t length_
 Length of the text. More...
 
bool surface_dirty_
 The dirty state of the surface. More...
 
std::vector< uint8_t > surface_buffer_
 Buffer to store the image on. More...
 

Detailed Description

Text class.

This class represents text which is rendered using Pango.

It takes text, as a utf-8 std::string, plus formatting options including font and color. It provides a surface object which holds the rendered text.

Besides this, it can do some additional calculations using the font layout.

It can take an index into the text, and convert it to pixel coordinates, so that if we want to draw a cursor in an editbox, we know where to draw it.

It can also take a pixel coordinate with respect to the text layout, and translate it back to an index into the original text. This is useful if the user clicks on the text, and we want to know where to move the cursor.

The get_token method takes a pixel coordinate, which we assume represents a click position, and gets the corresponding "token" from the string. The default token delimiters are whitespace " \n\r\t". So, this returns the "word" that the user clicked on.

Finally, the get_link method represents special support for hyperlinks in text. A token "looks like a link" if it begins "http://" or "https://". If a text has link_aware enabled, then any such token is rendered with an underline and in a special color, see link_color. The get_link method calls get_token and further checks if the clicked token looks like a link.

This class stores the text to draw and uses pango with the cairo backend to render the text. See http://pango.org for more info.

Definition at line 75 of file text.hpp.

Member Enumeration Documentation

Enumerator
STYLE_NORMAL 
STYLE_BOLD 
STYLE_ITALIC 
STYLE_UNDERLINE 
STYLE_LIGHT 

Definition at line 138 of file text.hpp.

Constructor & Destructor Documentation

font::pango_text::pango_text ( )

Definition at line 43 of file text.cpp.

font::pango_text::pango_text ( const pango_text )
delete

Member Function Documentation

PangoRectangle font::pango_text::calculate_size ( PangoLayout &  layout) const
private
void font::pango_text::copy_layout_properties ( PangoLayout &  src,
PangoLayout &  dst 
)
staticprivate

Definition at line 857 of file text.cpp.

Referenced by split_surface().

void font::pango_text::create_surface_buffer ( const size_t  size) const
private

Creates a new buffer.

If needed frees the other surface and then creates a new buffer and initializes the entire buffer with values 0.

NOTE eventhough we're clearly modifying function we don't change the state of the object. The const is needed so other functions can also be marked const (those also don't change the state of the object.

Parameters
sizeThe required size of the buffer.

Definition at line 730 of file text.cpp.

References surface::assign(), surface_, and surface_buffer_.

Referenced by rerender().

std::vector< std::string > font::pango_text::find_links ( utils::string_view  text) const
private
void font::pango_text::format_links ( std::string &  text,
const std::vector< std::string > &  links 
) const
private

Definition at line 791 of file text.cpp.

References font::format_as_link(), and link_color_.

Referenced by set_markup().

point font::pango_text::get_column_line ( const point position) const

Gets the column of line of the character at the position.

Parameters
positionThe pixel position in the text area.
Returns
A point with the x value the column and the y value the line of the character found (or last character if not found.
Todo:
There's still a bug left. When you select a text which is in the ellipses on the right side the text gets reformatted with ellipses on the left and the selected character is not the one under the cursor. Other widget toolkits don't show ellipses and have no indication more text is available. Haven't found what the best thing to do would be. Until that time leave it as is.

Definition at line 249 of file text.cpp.

References get_cursor_position(), i, utf8::index(), layout_, recalculate(), point::x, and point::y.

Referenced by gui2::text_box_base::get_column_line().

point font::pango_text::get_cursor_position ( const unsigned  column,
const unsigned  line = 0 
) const

Gets the location for the cursor.

Parameters
columnThe column offset of the cursor.
lineThe line offset of the cursor.
Returns
The position of the top of the cursor. It the requested location is out of range 0,0 is returned.

Definition at line 157 of file text.cpp.

References i, layout_, and recalculate().

Referenced by get_column_line(), and gui2::text_box_base::get_cursor_position().

int font::pango_text::get_height ( ) const

Returns the height needed for the text.

Definition at line 107 of file text.cpp.

References get_size(), and point::y.

size_t font::pango_text::get_length ( ) const
inline
std::string font::pango_text::get_link ( const point position) const

Checks if position points to a character in a link in the text, returns it if so, empty string otherwise.

Link-awareness must be enabled to get results.

Parameters
positionThe pixel position in the text area.
Returns
The link if one is found, the empty string otherwise.

Definition at line 234 of file text.cpp.

References get_token(), link_aware_, and font::looks_like_url().

Referenced by gui2::styled_widget::get_label_link().

point font::pango_text::get_size ( ) const

Returns the pixel size needed for the text.

Definition at line 112 of file text.cpp.

References recalculate(), and rect_.

Referenced by gui2::styled_widget::get_best_text_size(), get_height(), and get_width().

std::string font::pango_text::get_token ( const point position,
const char *  delimiters = " \n\r\t" 
) const

Gets the largest collection of characters, including the token at position, and not including any characters from the delimiters set.

Parameters
positionThe pixel position in the text area.
Returns
The token containing position, and none of the delimiter characters. If position is out of bounds, it returns the empty string.

Definition at line 202 of file text.cpp.

References d, utf8::index(), layout_, recalculate(), point::x, and point::y.

Referenced by gui2::styled_widget::get_label_token(), and get_link().

int font::pango_text::get_width ( ) const

Returns the width needed for the text.

Definition at line 102 of file text.cpp.

References get_size(), and point::x.

unsigned font::pango_text::insert_text ( const unsigned  offset,
const std::string &  text 
)

Inserts UTF-8 text.

Parameters
offsetThe position to insert the text.
textThe UTF-8 text to insert.
Returns
The number of characters inserted.

Definition at line 126 of file text.cpp.

References utf8::index(), utf8::insert(), length_, maximum_length_, set_text(), utf8::size(), and text_.

Referenced by gui2::text_box_base::insert_char(), insert_unicode(), and gui2::text_box_base::paste_selection().

bool font::pango_text::insert_unicode ( const unsigned  offset,
ucs4::char_t  unicode 
)

Inserts a unicode char.

Parameters
offsetThe position to insert the char.
unicodeThe character to insert.
Returns
True upon success, false otherwise.

Definition at line 146 of file text.cpp.

unsigned font::pango_text::insert_unicode ( const unsigned  offset,
const ucs4::string unicode 
)

Inserts unicode text.

Parameters
offsetThe position to insert the text.
unicodeVector with characters to insert.
Returns
The number of characters inserted.

Definition at line 151 of file text.cpp.

References utf8::insert(), insert_text(), and unicode_cast().

bool font::pango_text::is_surface_split ( ) const
inlineprivate

Definition at line 426 of file text.hpp.

Referenced by render().

bool font::pango_text::is_truncated ( ) const

Has the text been truncated? This happens if it exceeds max width or height.

Definition at line 119 of file text.cpp.

References layout_, and recalculate().

Referenced by gui2::styled_widget::get_best_text_size(), and gui2::styled_widget::place().

bool font::pango_text::link_aware ( ) const
inline

Definition at line 239 of file text.hpp.

References link_aware_.

pango_text& font::pango_text::operator= ( const pango_text )
delete
void font::pango_text::recalculate ( const bool  force = false) const
private

Recalculates the text layout.

When the text is recalculated the surface is dirtied.

Parameters
forceRecalculate even if not dirty?

Definition at line 489 of file text.cpp.

References calculate_size(), calculation_dirty_, layout_, rect_, and surface_dirty_.

Referenced by get_column_line(), get_cursor_position(), get_size(), get_token(), is_truncated(), and rerender().

surface & font::pango_text::render ( )

Returns the rendered text.

Before rendering it tests whether a redraw is needed and if so it first redraws the surface before returning it.

Definition at line 95 of file text.cpp.

References rerender(), and surface_.

Referenced by font::floating_label::create_surface(), gui2::text_shape::draw(), display::refresh_report(), render(), and rerender().

void font::pango_text::render ( PangoLayout &  layout,
const PangoRectangle &  rect,
const size_t  surface_buffer_offset,
const unsigned  stride 
)
private
void font::pango_text::rerender ( const bool  force = false)
private

Renders the text.

It will do a recalculation first so no need to call both.

Parameters
forceRender even if not dirty? This parameter is also send to recalculate().

Definition at line 684 of file text.cpp.

References surface::assign(), create_neutral_surface(), create_surface_buffer(), font::from_cairo_format(), layout_, maximum_height_, maximum_width_, recalculate(), rect_, render(), surface_, surface_buffer_, and surface_dirty_.

Referenced by render().

pango_text & font::pango_text::set_alignment ( const PangoAlignment  alignment)

Definition at line 443 of file text.cpp.

References alignment_, layout_, and surface_dirty_.

Referenced by gui2::text_shape::draw(), and gui2::styled_widget::get_best_text_size().

pango_text & font::pango_text::set_characters_per_line ( const unsigned  characters_per_line)
pango_text & font::pango_text::set_ellipse_mode ( const PangoEllipsizeMode  ellipse_mode)
pango_text & font::pango_text::set_family_class ( font::family_class  fclass)
pango_text & font::pango_text::set_font_size ( const unsigned  font_size)
pango_text & font::pango_text::set_font_style ( const FONT_STYLE  font_style)
pango_text & font::pango_text::set_foreground_color ( const color_t color)
pango_text & font::pango_text::set_link_aware ( bool  b)
pango_text & font::pango_text::set_link_color ( const color_t color)
bool font::pango_text::set_markup ( utils::string_view  text,
PangoLayout &  layout 
)
private

Sets the markup'ed text.

It tries to set the text as markup. If the markup is invalid it will try a bit harder to recover from the errors and still set the markup.

Parameters
textThe text to set as markup.
Returns
Whether the markup was set or an unrecoverable error occurred and the text is set as plain text with an error message.

Definition at line 739 of file text.cpp.

References _(), utils::basic_string_view< charT, traits >::data(), ERR_GUI_L, find_links(), format_links(), link_aware_, set_text(), utils::basic_string_view< charT, traits >::size(), utils::basic_string_view< charT, traits >::to_string(), and validate_markup().

Referenced by set_text(), and split_surface().

pango_text & font::pango_text::set_maximum_height ( int  height,
bool  multiline 
)
pango_text & font::pango_text::set_maximum_length ( const size_t  maximum_length)

Definition at line 454 of file text.cpp.

References length_, maximum_length_, set_text(), text_, and utf8::truncate().

Referenced by gui2::text_box_base::set_maximum_length().

pango_text & font::pango_text::set_maximum_width ( int  width)
bool font::pango_text::set_text ( const std::string &  text,
const bool  markedup 
)

Sets the text to render.

Parameters
textThe text to render.
markedupShould the text be rendered with pango markup. If the markup is invalid it's rendered as text without markup.
Returns
The status, if rendered as markup and the markup contains errors, false is returned else true.

Definition at line 283 of file text.cpp.

References calculation_dirty_, context_, ERR_GUI_L, layout_, length_, markedup_text_, set_markup(), sublayouts_, surface_dirty_, text(), text_, and unicode_cast().

Referenced by font::floating_label::create_surface(), gui2::text_shape::draw(), gui2::styled_widget::get_best_text_size(), gui2::text_box_base::handle_editing(), insert_text(), display::refresh_report(), set_markup(), set_maximum_length(), and gui2::text_box_base::set_value().

void font::pango_text::split_surface ( )
private

Splits the text to two Cairo surfaces.

The implementation isn't recursive: the function only splits the text once. As a result, it only doubles the maximum surface height to 64,000 pixels or so. The reason for this is that a recursive implementation would be more complex and it's unnecessary for now, as the longest surface in the game (end credits) is only about 40,000 pixels high with the default_large widget definition. If we need even larger surfaces in the future, the implementation can be made recursive.

Definition at line 836 of file text.cpp.

References context_, copy_layout_properties(), layout_, set_markup(), sublayouts_, text_, and utils::vertical_split().

Referenced by render().

const std::string& font::pango_text::text ( ) const
inline
bool font::pango_text::validate_markup ( utils::string_view  text,
char **  raw_text,
std::string &  semi_escaped 
) const
private

Member Data Documentation

PangoAlignment font::pango_text::alignment_
private

The alignment of the text.

Definition at line 328 of file text.hpp.

Referenced by set_alignment().

bool font::pango_text::calculation_dirty_
mutableprivate

The text has two dirty states:

  • The setting of the state and the size calculations.
  • The rendering of the surface.The dirty state of the calculations.

Definition at line 340 of file text.hpp.

Referenced by recalculate(), set_characters_per_line(), set_ellipse_mode(), set_family_class(), set_font_size(), set_font_style(), set_link_aware(), set_link_color(), set_maximum_height(), set_maximum_width(), and set_text().

unsigned font::pango_text::characters_per_line_
private

The number of characters per line.

This can be used as an alternative of maximum_width_. The user can select a number of characters on a line for wrapping. When the value is non-zero it determines the maximum width based on the average character width.

If both maximum_width_ and characters_per_line_ are set the minimum of the two will be the maximum.

Note
Long lines are often harder to read, setting this value can automatically wrap on a number of characters regardless of the font size. Often 66 characters is considered the optimal value for a one column text.

Definition at line 314 of file text.hpp.

Referenced by calculate_size(), and set_characters_per_line().

std::unique_ptr<PangoContext, std::function<void(void*)> > font::pango_text::context_
private

Definition at line 247 of file text.hpp.

Referenced by calculate_size(), set_text(), and split_surface().

PangoEllipsizeMode font::pango_text::ellipse_mode_
private

The way too long text is shown depends on this mode.

Definition at line 325 of file text.hpp.

Referenced by set_ellipse_mode().

font::family_class font::pango_text::font_class_
private

The font family class used.

Definition at line 277 of file text.hpp.

Referenced by calculate_size(), and set_family_class().

unsigned font::pango_text::font_size_
private

The font size to draw.

Definition at line 280 of file text.hpp.

Referenced by calculate_size(), and set_font_size().

FONT_STYLE font::pango_text::font_style_
private

The style of the font, this is an orred mask of the font flags.

Definition at line 283 of file text.hpp.

Referenced by calculate_size(), and set_font_style().

color_t font::pango_text::foreground_color_
private

The foreground color.

Definition at line 286 of file text.hpp.

Referenced by render(), and set_foreground_color().

std::unique_ptr<PangoLayout, std::function<void(void*)> > font::pango_text::layout_
private
size_t font::pango_text::length_
mutableprivate

Length of the text.

Definition at line 343 of file text.hpp.

Referenced by get_length(), insert_text(), set_maximum_length(), and set_text().

bool font::pango_text::link_aware_
private

Are hyperlinks in the text marked-up, and will get_link return them.

Definition at line 265 of file text.hpp.

Referenced by get_link(), link_aware(), set_link_aware(), and set_markup().

color_t font::pango_text::link_color_
private

The color to render links in.

Links are formatted using pango <span> as follows:

<span underline="single" color=" + link_color_ + ">

Definition at line 274 of file text.hpp.

Referenced by format_links(), and set_link_color().

bool font::pango_text::markedup_text_
private

Does the text contain pango markup? If different render routines must be used.

Definition at line 262 of file text.hpp.

Referenced by calculate_size(), and set_text().

int font::pango_text::maximum_height_
private

The maximum height of the text.

Values less or equal to 0 mean no maximum and are internally stored as -1, since that's the value pango uses for it.

Definition at line 322 of file text.hpp.

Referenced by calculate_size(), render(), rerender(), and set_maximum_height().

size_t font::pango_text::maximum_length_
private

The maximum length of the text.

Definition at line 331 of file text.hpp.

Referenced by insert_text(), and set_maximum_length().

int font::pango_text::maximum_width_
private

The maximum width of the text.

Values less or equal to 0 mean no maximum and are internally stored as -1, since that's the value pango uses for it.

See characters_per_line_.

Definition at line 296 of file text.hpp.

Referenced by calculate_size(), render(), rerender(), and set_maximum_width().

PangoRectangle font::pango_text::rect_
mutableprivate

Definition at line 249 of file text.hpp.

Referenced by get_size(), recalculate(), and rerender().

std::vector<std::unique_ptr<PangoLayout, std::function<void(void*)> > > font::pango_text::sublayouts_
private

Definition at line 252 of file text.hpp.

Referenced by render(), set_text(), and split_surface().

surface font::pango_text::surface_
mutableprivate

The SDL surface to render upon used as a cache.

Definition at line 255 of file text.hpp.

Referenced by create_surface_buffer(), render(), and rerender().

std::vector<uint8_t> font::pango_text::surface_buffer_
mutableprivate

Buffer to store the image on.

We use a cairo surface to draw on this buffer and then use the buffer as data source for the SDL_Surface. This means the buffer needs to be stored in the object, since SDL_Surface doesn't own its buffer.

Definition at line 380 of file text.hpp.

Referenced by create_surface_buffer(), render(), and rerender().

bool font::pango_text::surface_dirty_
mutableprivate
std::string font::pango_text::text_
private

The text to draw (stored as UTF-8).

Definition at line 259 of file text.hpp.

Referenced by calculate_size(), insert_text(), set_maximum_length(), set_text(), split_surface(), and text().


The documentation for this class was generated from the following files: