Gamedev Framework (gf)  0.3.0
A C++11 framework for 2D games
Text.h
1 /*
2  * Gamedev Framework (gf)
3  * Copyright (C) 2016 Julien Bernard
4  *
5  * This software is provided 'as-is', without any express or implied
6  * warranty. In no event will the authors be held liable for any damages
7  * arising from the use of this software.
8  *
9  * Permission is granted to anyone to use this software for any purpose,
10  * including commercial applications, and to alter it and redistribute it
11  * freely, subject to the following restrictions:
12  *
13  * 1. The origin of this software must not be misrepresented; you must not
14  * claim that you wrote the original software. If you use this software
15  * in a product, an acknowledgment in the product documentation would be
16  * appreciated but is not required.
17  * 2. Altered source versions must be plainly marked as such, and must not be
18  * misrepresented as being the original software.
19  * 3. This notice may not be removed or altered from any source distribution.
20  *
21  * Part of this file comes from SFML, with the same license:
22  * Copyright (C) 2007-2015 Laurent Gomila (laurent@sfml-dev.org)
23  */
24 #ifndef GF_TEXT_H
25 #define GF_TEXT_H
26 
27 #include <string>
28 
29 #include "Alignment.h"
30 #include "Portability.h"
31 #include "Transformable.h"
32 #include "Vector.h"
33 #include "VertexArray.h"
34 #include "VertexBuffer.h"
35 
36 namespace gf {
37 #ifndef DOXYGEN_SHOULD_SKIP_THIS
38 inline namespace v1 {
39 #endif
40 
41  class Font;
42 
43  /**
44  * @ingroup graphics
45  * @brief Graphical text that can be drawn to a render target
46  *
47  * gf::Text is a drawable class that allows to easily display
48  * some text with custom style and color on a render target.
49  *
50  * It inherits all the functions from gf::Transformable:
51  * position, rotation, scale, origin. It also adds text-specific
52  * properties such as the font to use, the character size, the
53  * global color and the text to display of course.
54  * It also provides convenience functions to calculate the
55  * graphical size of the text.
56  *
57  * gf::Text works in combination with the gf::Font class, which
58  * loads and provides the glyphs (visual characters) of a given font.
59  *
60  * The separation of gf::Font and gf::Text allows more flexibility
61  * and better performances: indeed a gf::Font is a heavy resource,
62  * and any operation on it is slow (often too slow for real-time
63  * applications). On the other side, a gf::Text is a lightweight
64  * object which can combine the glyphs data and metrics of a gf::Font
65  * to display any text on a render target.
66  *
67  * It is important to note that the gf::Text instance doesn't
68  * copy the font that it uses, it only keeps a reference to it.
69  * Thus, a gf::Font must not be destructed while it is
70  * used by a gf::Text (i.e. never write a function that
71  * uses a local gf::Font instance for creating a text).
72  *
73  * Usage example:
74  *
75  * ~~~{.cc}
76  * // Declare and load a font
77  * gf::Font font;
78  * font.loadFromFile("arial.ttf");
79  *
80  * // Create a text
81  * gf::Text text("hello", font);
82  * text.setCharacterSize(30);
83  * text.setColor(gf::Color::Red);
84  *
85  * // Draw it
86  * rendered.draw(text);
87  * ~~~
88  *
89  * @sa gf::Font
90  */
91  class GF_API Text : public Transformable {
92  public:
93  /**
94  * @brief Default constructor
95  *
96  * Creates an empty text.
97  */
98  Text();
99 
100  /**
101  * @brief Construct the text from a string, font and size
102  *
103  * @param string Text assigned to the string in UTF-8 format
104  * @param font Font used to draw the string
105  * @param characterSize Base size of characters, in pixels
106  */
107  Text(std::string string, Font& font, unsigned characterSize = 30);
108 
109  /**
110  * @brief Set the text's string
111  *
112  * The text string is in UTF-8 format.
113  * A text's string is empty by default.
114  *
115  * @param string New string in UTF-8 format
116  *
117  * @sa getString()
118  */
119  void setString(std::string string);
120 
121  /**
122  * @brief Get the text's string
123  *
124  * The text string is in UTF-8 format.
125  *
126  * @return Text's string
127  *
128  * @sa setString()
129  */
130  const std::string& getString() const {
131  return m_string;
132  }
133 
134  /**
135  * @brief Set the character size
136  *
137  * The default size is 30.
138  *
139  * @param characterSize New character size, in pixels
140  *
141  * @sa getCharacterSize()
142  */
143  void setCharacterSize(unsigned characterSize);
144 
145  /**
146  * @brief Get the character size
147  *
148  * @return Size of the characters, in pixels
149  *
150  * @sa setCharacterSize()
151  */
152  unsigned getCharacterSize() const {
153  return m_characterSize;
154  }
155 
156  /**
157  * @brief Set the text's font
158  *
159  * The `font` argument refers to a font that must
160  * exist as long as the text uses it. Indeed, the text
161  * doesn't store its own copy of the font, but rather keeps
162  * a pointer to the one that you passed to this function.
163  * If the font is destroyed and the text tries to
164  * use it, the behavior is undefined.
165  *
166  * @param font New font
167  *
168  * @sa getFont()
169  */
170  void setFont(Font& font);
171 
172  /**
173  * @brief Get the text's font
174  *
175  * If the text has no font attached, a `nullptr` pointer is returned.
176  * The returned pointer is const, which means that you
177  * cannot modify the font when you get it from this function.
178  *
179  * @return Pointer to the text's font
180  *
181  * @sa setFont()
182  */
183  const Font *getFont() const {
184  return m_font;
185  }
186 
187  /**
188  * @brief Set the fill color of the text
189  *
190  * By default, the text's fill color is opaque black.
191  * Setting the fill color to a transparent color with an outline
192  * will cause the outline to be displayed in the fill area of the text.
193  *
194  * @param color New fill color of the text
195  *
196  * @sa getColor()
197  */
198  void setColor(const Color4f& color);
199 
200  /**
201  * @brief Get the fill color of the text
202  *
203  * @return Fill color of the text
204  *
205  * @sa setColor()
206  */
207  const Color4f& getColor() const {
208  return m_color;
209  }
210 
211  /**
212  * @brief Set the outline color of the text
213  *
214  * By default, the text's outline color is opaque black.
215  *
216  * @param color New outline color of the text
217  *
218  * @sa getOutlineColor()
219  */
220  void setOutlineColor(const Color4f& color);
221 
222  /**
223  * @brief Get the outline color of the text
224  *
225  * @return Outline color of the text
226  *
227  * @sa setOutlineColor()
228  */
229  const Color4f& getOutlineColor() const {
230  return m_outlineColor;
231  }
232 
233  /**
234  * @brief Set the thickness of the text's outline
235  *
236  * By default, the outline thickness is 0.
237  *
238  * @param thickness New outline thickness, in pixels
239  *
240  * @sa getOutlineThickness()
241  */
242  void setOutlineThickness(float thickness);
243 
244  /**
245  * @brief Get the outline thickness of the text
246  *
247  * @return Outline thickness of the text, in pixels
248  *
249  * @sa setOutlineThickness()
250  */
252  return m_outlineThickness;
253  }
254 
255  /**
256  * @brief Set the paragraph width for aligned text
257  *
258  * By default, the paragraph width is 0.
259  *
260  * @param paragraphWidth New paragraph width in pixels
261  * @sa getParagraphWidth()
262  */
263  void setParagraphWidth(float paragraphWidth);
264 
265  /**
266  * @brief Get the paragraph width
267  *
268  * @return Paragraph width in pixels
269  * @sa setParagraphWidth()
270  */
271  float getParagraphWidth() const {
272  return m_paragraphWidth;
273  }
274 
275  /**
276  * @brief Set the alignement of the text
277  *
278  * By default, the text is not aligned.
279  *
280  * @param align New alignement
281  * @sa getAlignment()
282  */
283  void setAlignment(Alignment align);
284 
285  /**
286  * @brief Get the alignment of the text
287  *
288  * @return Current alignment of the text
289  * @sa setAlignment()
290  */
292  return m_align;
293  }
294 
295  /**
296  * @brief Get the local bounding rectangle of the entity
297  *
298  * The returned rectangle is in local coordinates, which means
299  * that it ignores the transformations (translation, rotation,
300  * scale, ...) that are applied to the entity.
301  * In other words, this function returns the bounds of the
302  * entity in the entity's coordinate system.
303  *
304  * @return Local bounding rectangle of the entity
305  */
306  RectF getLocalBounds() const {
307  return m_bounds;
308  }
309 
310  /**
311  * @brief Set the anchor origin of the entity
312  *
313  * Compute the origin of the entity based on the local bounds and
314  * the specified anchor. Internally, this function calls
315  * `Transformable::setOrigin()`.
316  *
317  * @param anchor The anchor of the entity
318  * @sa getLocalBounds(), Transformable::setOrigin()
319  */
320  void setAnchor(Anchor anchor);
321 
322  /**
323  * @brief Create a buffer with the current geometry
324  *
325  * The geometry is uploaded in the graphics memory so that it's faster
326  * to draw.
327  *
328  * @return A buffer with the current geometry
329  */
331 
332  /**
333  * @brief Create a buffer with the current outline geometry
334  *
335  * The geometry is uploaded in the graphics memory so that it's faster
336  * to draw.
337  *
338  * @return A buffer with the current outline geometry
339  */
341 
342  virtual void draw(RenderTarget& target, RenderStates states) override;
343 
344  private:
345  void updateGeometry();
346 
347  private:
348  struct Line {
349  std::vector<std::u32string> words;
350  float indent = 0.0f;
351  float spacing = 0.0f;
352  };
353 
354  struct Paragraph {
355  std::vector<Line> lines;
356  };
357 
358  float getWordWidth(const std::u32string& word);
359 
360  std::vector<Paragraph> makeParagraphs(const std::string& str, float spaceWidth);
361 
362  private:
363  std::string m_string;
364  Font *m_font;
365  unsigned m_characterSize;
366  Color4f m_color;
367  VertexArray m_vertices;
368  RectF m_bounds;
369 
370  Color4f m_outlineColor;
371  float m_outlineThickness;
372  VertexArray m_outlineVertices;
373 
374  float m_paragraphWidth;
375  Alignment m_align;
376  };
377 
378 #ifndef DOXYGEN_SHOULD_SKIP_THIS
379 }
380 #endif
381 }
382 
383 #endif // GF_TEXT_H
Decomposed transform defined by a position, a rotation and a scale.
Definition: Transformable.h:113
void setAnchor(Anchor anchor)
Set the anchor origin of the entity.
float getOutlineThickness()
Get the outline thickness of the text.
Definition: Text.h:251
void setColor(const Color4f &color)
Set the fill color of the text.
void setFont(Font &font)
Set the text's font.
A set of primitives.
Definition: VertexArray.h:65
Text()
Default constructor.
Base class for all render targets (window, texture, ...)
Definition: RenderTarget.h:65
Define the states used for drawing to a RenderTarget.
Definition: RenderStates.h:82
const Color4f & getColor() const
Get the fill color of the text.
Definition: Text.h:207
unsigned getCharacterSize() const
Get the character size.
Definition: Text.h:152
virtual void draw(RenderTarget &target, RenderStates states) override
Draw the object to a render target.
Data in the graphics memory.
Definition: VertexBuffer.h:70
void setOutlineThickness(float thickness)
Set the thickness of the text's outline.
RectF getLocalBounds() const
Get the local bounding rectangle of the entity.
Definition: Text.h:306
void setOutlineColor(const Color4f &color)
Set the outline color of the text.
void setAlignment(Alignment align)
Set the alignement of the text.
Alignment getAlignment() const
Get the alignment of the text.
Definition: Text.h:291
Graphical text that can be drawn to a render target.
Definition: Text.h:91
VertexBuffer commitGeometry() const
Create a buffer with the current geometry.
const std::string & getString() const
Get the text's string.
Definition: Text.h:130
void setParagraphWidth(float paragraphWidth)
Set the paragraph width for aligned text.
Definition: Action.h:34
void setString(std::string string)
Set the text's string.
Text(std::string string, Font &font, unsigned characterSize=30)
Construct the text from a string, font and size.
A character font.
Definition: Font.h:130
float getParagraphWidth() const
Get the paragraph width.
Definition: Text.h:271
const Color4f & getOutlineColor() const
Get the outline color of the text.
Definition: Text.h:229
Anchor
The origin anchor of the transformable object.
Definition: Transformable.h:45
const Font * getFont() const
Get the text's font.
Definition: Text.h:183
Alignment
The alignement of a text.
Definition: Alignment.h:33
#define GF_API
Definition: Portability.h:35
VertexBuffer commitOutlineGeometry() const
Create a buffer with the current outline geometry.
void setCharacterSize(unsigned characterSize)
Set the character size.