The Battle for Wesnoth  1.19.0-dev
text.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2008 - 2024
3  by Mark de Wever <koraq@xs4all.nl>
4  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
5 
6  This program is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by
8  the Free Software Foundation; either version 2 of the License, or
9  (at your option) any later version.
10  This program is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY.
12 
13  See the COPYING file for more details.
14 */
15 
16 #pragma once
17 
18 #include "font/font_options.hpp"
19 #include "color.hpp"
20 #include "sdl/surface.hpp"
21 #include "sdl/texture.hpp"
23 
24 #include <pango/pangocairo.h>
25 
26 
27 #include <functional>
28 #include <memory>
29 #include <string>
30 #include <vector>
31 
32 /***
33  * Note: This is the cairo-pango code path, not the SDL_TTF code path.
34  */
35 
36 struct point;
37 
38 namespace font {
39 
40 /** Flush the rendered text cache. */
41 void flush_texture_cache();
42 
43 // add background color and also font markup.
44 
45 /**
46  * Text class.
47  *
48  * This class represents text which is rendered using Pango.
49  *
50  * It takes text, as a utf-8 std::string, plus formatting options including
51  * font and color. It provides a surface object which holds the rendered text.
52  *
53  * Besides this, it can do some additional calculations using the font layout.
54  *
55  * It can take an index into the text, and convert it to pixel coordinates,
56  * so that if we want to draw a cursor in an editbox, we know where to draw it.
57  *
58  * It can also take a pixel coordinate with respect to the text layout, and
59  * translate it back to an index into the original text. This is useful if the
60  * user clicks on the text, and we want to know where to move the cursor.
61  *
62  * The get_token method takes a pixel coordinate, which we assume represents a
63  * click position, and gets the corresponding "token" from the string. The default
64  * token delimiters are whitespace " \n\r\t". So, this returns the "word" that the
65  * user clicked on.
66  *
67  * Finally, the get_link method represents special support for hyperlinks in text.
68  * A token "looks like a link" if it begins "http://" or "https://".
69  * If a text has link_aware enabled, then any such token is rendered with an
70  * underline and in a special color, see `link_color`.
71  * The get_link method calls get_token and further checks if the clicked token
72  * looks like a link.
73  *
74  * This class stores the text to draw and uses pango with the cairo backend to
75  * render the text. See http://pango.org for more info.
76  *
77  */
79 {
80 public:
81  pango_text();
82 
83  pango_text(const pango_text&) = delete;
84  pango_text& operator=(const pango_text&) = delete;
85 
86  /**
87  * Returns the cached texture, or creates a new one otherwise.
88  *
89  * texture::w() and texture::h() methods will return the expected
90  * width and height of the texture in draw space. This may differ
91  * from the real value returned by texture::get_info().
92  *
93  * In almost all cases, use w() and h() to get the size of the
94  * rendered text for drawing.
95  */
97 
98 private:
99  /**
100  * Wrapper around render_surface which sets texture::w() and texture::h()
101  * in the same way that render_and_get_texture does.
102  *
103  * The viewport rect is interpreted at the scale of render-space, not
104  * drawing-space. This function has only been made private to preserve
105  * the drawing-space encapsulation.
106  */
107  texture render_texture(const SDL_Rect& viewport);
108 
109  /**
110  * Returns the rendered text.
111  *
112  * The viewport rect is interpreted at the scale of render-space, not
113  * drawing-space. This function has only been made private to preserve
114  * the drawing-space encapsulation.
115  *
116  * @param viewport Only this area needs to be drawn - the returned
117  * surface's origin will correspond to viewport.x and viewport.y, the
118  * width and height will be at least viewport.w and viewport.h (although
119  * they may be larger).
120  */
121  surface render_surface(const SDL_Rect& viewport);
122 
123 public:
124  /** Returns the size of the text, in drawing coordinates. */
125  point get_size();
126 
127  /** Has the text been truncated? This happens if it exceeds max width or height. */
128  bool is_truncated() const;
129 
130  /**
131  * Inserts UTF-8 text.
132  *
133  * @param offset The position to insert the text.
134  * @param text The UTF-8 text to insert.
135  *
136  * @returns The number of characters inserted.
137  */
138  unsigned insert_text(const unsigned offset, const std::string& text);
139 
140  /***** ***** ***** ***** Font flags ***** ***** ***** *****/
141 
142  // NOTE: these values must be powers of 2 in order to be bit-unique
143  enum FONT_STYLE {
148  };
149 
150  /***** ***** ***** ***** Query details ***** ***** ***** *****/
151 
152  /**
153  * Returns the maximum glyph height of a font, in drawing coordinates.
154  *
155  * @returns The height of the tallest possible glyph for the selected
156  * font. More specifically, the result is the sum of the maximum
157  * ascent and descent lengths.
158  */
159  int get_max_glyph_height() const;
160 
161  /**
162  * Gets the location for the cursor, in drawing coordinates.
163  *
164  * @param column The column offset of the cursor.
165  * @param line The line offset of the cursor.
166  *
167  * @returns The position of the top of the cursor. It the
168  * requested location is out of range 0,0 is
169  * returned.
170  */
172  const unsigned column, const unsigned line = 0) const;
173 
174  /**
175  * Gets the correct number of columns to move the cursor
176  * from Pango. Needed in case the text contains multibyte
177  * characters. Return value == column if the text has no
178  * multibyte characters.
179  *
180  * @param column The column offset of the cursor.
181  *
182  * @returns Corrected column offset.
183  */
184  int get_byte_offset(const unsigned column) const;
185 
186  /**
187  * Get maximum length.
188  *
189  * @returns The maximum length of the text. The length of text
190  * should not exceed this value.
191  */
192  std::size_t get_maximum_length() const;
193 
194  /**
195  * Gets the largest collection of characters, including the token at position,
196  * and not including any characters from the delimiters set.
197  *
198  * @param position The pixel position in the text area.
199  * @param delimiters
200  *
201  * @returns The token containing position, and none of the
202  * delimiter characters. If position is out of bounds,
203  * it returns the empty string.
204  */
205  std::string get_token(const point & position, const char * delimiters = " \n\r\t") const;
206 
207  /**
208  * Checks if position points to a character in a link in the text, returns it
209  * if so, empty string otherwise. Link-awareness must be enabled to get results.
210  * @param position The pixel position in the text area.
211  *
212  * @returns The link if one is found, the empty string otherwise.
213  */
214  std::string get_link(const point & position) const;
215 
216  /**
217  * Gets the column of line of the character at the position.
218  *
219  * @param position The pixel position in the text area.
220  *
221  * @returns A point with the x value the column and the y
222  * value the line of the character found (or last
223  * character if not found.
224  */
225  point get_column_line(const point& position) const;
226 
227  /**
228  * Retrieves a list of strings with contents for each rendered line.
229  *
230  * This method is not const because it requires rendering the text.
231  *
232  * @note This is only intended for renderer implementation details. This
233  * is a rather expensive function because it copies everything at
234  * least once.
235  */
236  std::vector<std::string> get_lines() const;
237 
238  /**
239  * Get number of lines in the text.
240  *
241  * @returns The number of lines in the text.
242  *
243  */
244  unsigned get_lines_count() const { return pango_layout_get_line_count(layout_.get()); };
245 
246  /**
247  * Gets the length of the text in bytes.
248  *
249  * The text set is UTF-8 so the length of the string might not be the length
250  * of the text.
251  */
252  std::size_t get_length() const { return length_; }
253 
254  /**
255  * Sets the text to render.
256  *
257  * @param text The text to render.
258  * @param markedup Should the text be rendered with pango
259  * markup. If the markup is invalid it's
260  * rendered as text without markup.
261  *
262  * @returns The status, if rendered as markup and the
263  * markup contains errors, false is returned
264  * else true.
265  */
266  bool set_text(const std::string& text, const bool markedup);
267 
268  /***** ***** ***** ***** Setters / getters ***** ***** ***** *****/
269 
270  const std::string& text() const { return text_; }
271 
273 
274  pango_text& set_font_size(unsigned font_size);
275 
276  pango_text& set_font_style(const FONT_STYLE font_style);
277 
278  pango_text& set_foreground_color(const color_t& color);
279 
280  pango_text& set_maximum_width(int width);
281 
282  pango_text& set_characters_per_line(const unsigned characters_per_line);
283 
284  pango_text& set_maximum_height(int height, bool multiline);
285 
286  pango_text& set_ellipse_mode(const PangoEllipsizeMode ellipse_mode);
287 
288  pango_text& set_alignment(const PangoAlignment alignment);
289 
290  pango_text& set_maximum_length(const std::size_t maximum_length);
291 
292  bool link_aware() const { return link_aware_; }
293 
294  pango_text& set_link_aware(bool b);
295 
296  pango_text& set_link_color(const color_t& color);
297 
298  pango_text& set_add_outline(bool do_add);
299 
300  /**
301  * Mark a specific portion of text for highlighting. Used for selection box.
302  * BGColor is set in set_text(), this just marks the area to be colored.
303  * Markup not used because the user may enter their own markup or special characters
304  * @param start_offset Column offset of the cursor where selection/highlight starts
305  * @param end_offset Column offset of the cursor where selection/highlight ends
306  * @param color Highlight color
307  */
308  void set_highlight_area(const unsigned start_offset, const unsigned end_offset, const color_t& color)
309  {
310  highlight_start_offset_ = start_offset;
311  highlight_end_offset_ = end_offset;
312  highlight_color_ = color;
313  }
314 
315 private:
316 
317  /***** ***** ***** ***** Pango variables ***** ***** ***** *****/
318  std::unique_ptr<PangoContext, std::function<void(void*)>> context_;
319  std::unique_ptr<PangoLayout, std::function<void(void*)>> layout_;
320  mutable PangoRectangle rect_;
321 
322  /** The text to draw (stored as UTF-8). */
323  std::string text_;
324 
325  /** Does the text contain pango markup? If different render routines must be used. */
327 
328  /** Are hyperlinks in the text marked-up, and will get_link return them. */
330 
331  /**
332  * The color to render links in.
333  *
334  * Links are formatted using pango &lt;span> as follows:
335  *
336  * &lt;span underline="single" color=" + link_color_ + ">
337  */
339 
340  /** The font family class used. */
342 
343  /** The font size to draw. */
344  unsigned font_size_;
345 
346  /** The style of the font, this is an orred mask of the font flags. */
348 
349  /** The foreground color. */
351 
352  /** Whether to add an outline effect. */
354 
355  /**
356  * The maximum width of the text.
357  *
358  * Values less or equal to 0 mean no maximum and are internally stored as
359  * -1, since that's the value pango uses for it.
360  *
361  * See @ref characters_per_line_.
362  */
364 
365  /**
366  * The number of characters per line.
367  *
368  * This can be used as an alternative of @ref maximum_width_. The user can
369  * select a number of characters on a line for wrapping. When the value is
370  * non-zero it determines the maximum width based on the average character
371  * width.
372  *
373  * If both @ref maximum_width_ and @ref characters_per_line_ are set the
374  * minimum of the two will be the maximum.
375  *
376  * @note Long lines are often harder to read, setting this value can
377  * automatically wrap on a number of characters regardless of the font
378  * size. Often 66 characters is considered the optimal value for a one
379  * column text.
380  */
382 
383  /**
384  * The maximum height of the text.
385  *
386  * Values less or equal to 0 mean no maximum and are internally stored as
387  * -1, since that's the value pango uses for it.
388  */
390 
391  /** The way too long text is shown depends on this mode. */
392  PangoEllipsizeMode ellipse_mode_;
393 
394  /** The alignment of the text. */
395  PangoAlignment alignment_;
396 
397  /** The maximum length of the text. */
398  std::size_t maximum_length_;
399 
400  /**
401  * The text has two dirty states:
402  * - The setting of the state and the size calculations.
403  * - The rendering of the surface.
404  */
405 
406  /** The dirty state of the calculations. */
407  mutable bool calculation_dirty_;
408 
409  /** Length of the text. */
410  mutable std::size_t length_;
411 
415 
416  /** The pixel scale, used to render high-DPI text. */
418 
419  /** Recalculates the text layout. */
420  void recalculate() const;
421 
422  /** Calculates surface size. */
423  PangoRectangle calculate_size(PangoLayout& layout) const;
424 
425  /** Allow specialization of std::hash for pango_text. */
426  friend struct std::hash<pango_text>;
427 
428  /**
429  * Equivalent to create_surface(viewport), where the viewport's top-left is
430  * at (0,0) and the area is large enough to contain the full text.
431  *
432  * The top-left of the viewport will be at (0,0), regardless of the values
433  * of x and y in the rect_ member variable. If the x or y co-ordinates are
434  * non-zero, then x columns and y rows of blank space are included in the
435  * amount of memory allocated.
436  */
438 
439  /**
440  * Renders the text to a surface that uses surface_buffer_ as its data store,
441  * the buffer will be allocated or reallocated as necessary.
442  *
443  * The surface's origin will correspond to viewport.x and viewport.y, the
444  * width and height will be at least viewport.w and viewport.h (although
445  * they may be larger).
446  *
447  * @param viewport The area to draw, which can be a subset of the text. This
448  * rectangle's coordinates use render-space's scale.
449  */
450  surface create_surface(const SDL_Rect& viewport);
451 
452  /**
453  * This is part of create_surface(viewport). The separation is a legacy
454  * from workarounds to the size limits of cairo_surface_t.
455  */
456  void render(PangoLayout& layout, const SDL_Rect& viewport, const unsigned stride);
457 
458  /**
459  * Buffer to store the image on.
460  *
461  * We use a cairo surface to draw on this buffer and then use the buffer as
462  * data source for the SDL_Surface. This means the buffer needs to be stored
463  * in the object, since SDL_Surface doesn't own its buffer.
464  */
465  mutable std::vector<uint8_t> surface_buffer_;
466 
467  /**
468  * Sets the markup'ed text.
469  *
470  * It tries to set the text as markup. If the markup is invalid it will try
471  * a bit harder to recover from the errors and still set the markup.
472  *
473  * @param text The text to set as markup.
474  * @param layout
475  *
476  * @returns Whether the markup was set or an
477  * unrecoverable error occurred and the text is
478  * set as plain text with an error message.
479  */
480  bool set_markup(std::string_view text, PangoLayout& layout);
481 
482  bool validate_markup(std::string_view text, char** raw_text, std::string& semi_escaped) const;
483 
484  static void copy_layout_properties(PangoLayout& src, PangoLayout& dst);
485 
486  std::string format_links(std::string_view text) const;
487 
488  /**
489  * Adjust a texture's draw-width and height according to pixel scale.
490  *
491  * As fonts are rendered at output-scale, we need to do this just
492  * before returning the rendered texture. These attributes are stored
493  * as part of the returned texture object.
494  */
495  texture with_draw_scale(const texture& t) const;
496 
497  /** Scale the given render-space size to draw-space, rounding up. */
498  int to_draw_scale(int s) const;
499 
500  /** Scale the given render-space point to draw-space, rounding up. */
501  point to_draw_scale(const point& p) const;
502 
503  /** Update pixel scale, if necessary. */
504  void update_pixel_scale();
505 };
506 
507 /**
508  * Returns a reference to a static pango_text object.
509  *
510  * Since the class is essentially a render pipeline, there's no need for individual
511  * areas of the game to own their own renderers. Not to mention it isn't a trivial
512  * class; constructing one is likely to be expensive.
513  */
515 
516 /**
517  * Returns the maximum glyph height of a font, in pixels.
518  *
519  * @param size Desired font size in pixels.
520  * @param fclass Font family to use for measurement.
521  * @param style Font style to select the correct variant for measurement.
522  *
523  * @returns The height of the tallest possible glyph for the selected
524  * font. More specifically, the result is the sum of the maximum
525  * ascent and descent lengths.
526  */
528 
529 /* Returns the default line spacing factor
530  * For now hardcoded here */
531 constexpr float get_line_spacing_factor() { return 1.3f; };
532 
533 } // namespace font
534 
535 // Specialize std::hash for pango_text
536 namespace std
537 {
538 template<>
539 struct hash<font::pango_text>
540 {
541  std::size_t operator()(const font::pango_text&) const;
542 };
543 
544 } // namespace std
double t
Definition: astarsearch.cpp:63
Text class.
Definition: text.hpp:79
unsigned get_lines_count() const
Get number of lines in the text.
Definition: text.hpp:244
int pixel_scale_
The pixel scale, used to render high-DPI text.
Definition: text.hpp:417
pango_text & operator=(const pango_text &)=delete
pango_text & set_font_style(const FONT_STYLE font_style)
Definition: text.cpp:424
PangoEllipsizeMode ellipse_mode_
The way too long text is shown depends on this mode.
Definition: text.hpp:392
void set_highlight_area(const unsigned start_offset, const unsigned end_offset, const color_t &color)
Mark a specific portion of text for highlighting.
Definition: text.hpp:308
static void copy_layout_properties(PangoLayout &src, PangoLayout &dst)
Definition: text.cpp:968
bool add_outline_
Whether to add an outline effect.
Definition: text.hpp:353
bool validate_markup(std::string_view text, char **raw_text, std::string &semi_escaped) const
Definition: text.cpp:930
bool set_markup(std::string_view text, PangoLayout &layout)
Sets the markup'ed text.
Definition: text.cpp:862
int get_byte_offset(const unsigned column) const
Gets the correct number of columns to move the cursor from Pango.
Definition: text.cpp:192
std::size_t get_length() const
Gets the length of the text in bytes.
Definition: text.hpp:252
pango_text & set_maximum_length(const std::size_t maximum_length)
Definition: text.cpp:525
void render(PangoLayout &layout, const SDL_Rect &viewport, const unsigned stride)
This is part of create_surface(viewport).
Definition: text.cpp:761
unsigned insert_text(const unsigned offset, const std::string &text)
Inserts UTF-8 text.
Definition: text.cpp:172
surface create_surface()
Equivalent to create_surface(viewport), where the viewport's top-left is at (0,0) and the area is lar...
Definition: text.cpp:812
PangoAlignment alignment_
The alignment of the text.
Definition: text.hpp:395
PangoRectangle rect_
Definition: text.hpp:320
int maximum_height_
The maximum height of the text.
Definition: text.hpp:389
point get_size()
Returns the size of the text, in drawing coordinates.
Definition: text.cpp:157
pango_text & set_characters_per_line(const unsigned characters_per_line)
Definition: text.cpp:459
color_t link_color_
The color to render links in.
Definition: text.hpp:338
void recalculate() const
Recalculates the text layout.
Definition: text.cpp:608
color_t foreground_color_
The foreground color.
Definition: text.hpp:350
point get_column_line(const point &position) const
Gets the column of line of the character at the position.
Definition: text.cpp:311
std::unique_ptr< PangoContext, std::function< void(void *)> > context_
Definition: text.hpp:318
bool link_aware_
Are hyperlinks in the text marked-up, and will get_link return them.
Definition: text.hpp:329
pango_text & set_foreground_color(const color_t &color)
Definition: text.cpp:434
int to_draw_scale(int s) const
Scale the given render-space size to draw-space, rounding up.
Definition: text.cpp:146
std::string format_links(std::string_view text) const
Replaces all instances of URLs in a given string with formatted links and returns the result.
Definition: text.cpp:892
pango_text(const pango_text &)=delete
unsigned characters_per_line_
The number of characters per line.
Definition: text.hpp:381
bool markedup_text_
Does the text contain pango markup? If different render routines must be used.
Definition: text.hpp:326
pango_text & set_family_class(font::family_class fclass)
Definition: text.cpp:402
font::family_class font_class_
The font family class used.
Definition: text.hpp:341
std::vector< std::string > get_lines() const
Retrieves a list of strings with contents for each rendered line.
Definition: text.cpp:975
void update_pixel_scale()
Update pixel scale, if necessary.
Definition: text.cpp:587
bool link_aware() const
Definition: text.hpp:292
unsigned font_size_
The font size to draw.
Definition: text.hpp:344
texture render_texture(const SDL_Rect &viewport)
Wrapper around render_surface which sets texture::w() and texture::h() in the same way that render_an...
Definition: text.cpp:107
surface render_surface(const SDL_Rect &viewport)
Returns the rendered text.
Definition: text.cpp:132
std::vector< uint8_t > surface_buffer_
Buffer to store the image on.
Definition: text.hpp:465
pango_text & set_add_outline(bool do_add)
Definition: text.cpp:557
pango_text & set_ellipse_mode(const PangoEllipsizeMode ellipse_mode)
Definition: text.cpp:495
PangoRectangle calculate_size(PangoLayout &layout) const
Calculates surface size.
Definition: text.cpp:622
unsigned highlight_end_offset_
Definition: text.hpp:413
color_t highlight_color_
Definition: text.hpp:414
pango_text & set_alignment(const PangoAlignment alignment)
Definition: text.cpp:515
std::string text_
The text to draw (stored as UTF-8).
Definition: text.hpp:323
point get_cursor_position(const unsigned column, const unsigned line=0) const
Gets the location for the cursor, in drawing coordinates.
Definition: text.cpp:215
bool calculation_dirty_
The text has two dirty states:
Definition: text.hpp:407
std::unique_ptr< PangoLayout, std::function< void(void *)> > layout_
Definition: text.hpp:319
pango_text & set_font_size(unsigned font_size)
Definition: text.cpp:412
pango_text & set_link_aware(bool b)
Definition: text.cpp:538
FONT_STYLE font_style_
The style of the font, this is an orred mask of the font flags.
Definition: text.hpp:347
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 cha...
Definition: text.cpp:264
bool set_text(const std::string &text, const bool markedup)
Sets the text to render.
Definition: text.cpp:345
bool is_truncated() const
Has the text been truncated? This happens if it exceeds max width or height.
Definition: text.cpp:165
texture with_draw_scale(const texture &t) const
Adjust a texture's draw-width and height according to pixel scale.
Definition: text.cpp:139
std::size_t maximum_length_
The maximum length of the text.
Definition: text.hpp:398
pango_text & set_maximum_height(int height, bool multiline)
Definition: text.cpp:470
pango_text & set_maximum_width(int width)
Definition: text.cpp:443
std::size_t get_maximum_length() const
Get maximum length.
Definition: text.cpp:259
unsigned highlight_start_offset_
Definition: text.hpp:412
texture render_and_get_texture()
Returns the cached texture, or creates a new one otherwise.
Definition: text.cpp:112
pango_text & set_link_color(const color_t &color)
Definition: text.cpp:547
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 otherw...
Definition: text.cpp:296
const std::string & text() const
Definition: text.hpp:270
std::size_t length_
Length of the text.
Definition: text.hpp:410
int get_max_glyph_height() const
Returns the maximum glyph height of a font, in drawing coordinates.
Definition: text.cpp:567
int maximum_width_
The maximum width of the text.
Definition: text.hpp:363
Wrapper class to encapsulate creation and management of an SDL_Texture.
Definition: texture.hpp:33
static void layout()
void line(int from_x, int from_y, int to_x, int to_y)
Draw a line.
Definition: draw.cpp:180
Collection of helper functions relating to Pango formatting.
family_class
Font classes for get_font_families().
@ FONT_SANS_SERIF
int get_max_height(unsigned size, font::family_class fclass, pango_text::FONT_STYLE style)
Returns the maximum glyph height of a font, in pixels.
Definition: text.cpp:1007
pango_text & get_text_renderer()
Returns a reference to a static pango_text object.
Definition: text.cpp:1001
constexpr float get_line_spacing_factor()
Definition: text.hpp:531
void flush_texture_cache()
Flush the rendered text cache.
Definition: text.cpp:61
std::size_t size(const std::string &str)
Length in characters of a UTF-8 string.
Definition: unicode.cpp:85
The basic class for representing 8-bit RGB or RGBA colour values.
Definition: color.hpp:59
Holds a 2D point.
Definition: point.hpp:25
mock_party p
static map_location::DIRECTION s
#define b