git.sesse.net Git - casparcg/blob - dependencies64/sfml/include/SFML/Graphics/Text.hpp

   1 ////////////////////////////////////////////////////////////
   2 //
   3 // SFML - Simple and Fast Multimedia Library
   4 // Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
   5 //
   6 // This software is provided 'as-is', without any express or implied warranty.
   7 // In no event will the authors be held liable for any damages 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 freely,
  11 // subject to the following restrictions:
  12 //
  13 // 1. The origin of this software must not be misrepresented;
  14 //    you must not claim that you wrote the original software.
  15 //    If you use this software in a product, an acknowledgment
  16 //    in the product documentation would be appreciated but is not required.
  17 //
  18 // 2. Altered source versions must be plainly marked as such,
  19 //    and must not be misrepresented as being the original software.
  20 //
  21 // 3. This notice may not be removed or altered from any source distribution.
  22 //
  23 ////////////////////////////////////////////////////////////
  24
  25 #ifndef SFML_TEXT_HPP
  26 #define SFML_TEXT_HPP
  27
  28 ////////////////////////////////////////////////////////////
  29 // Headers
  30 ////////////////////////////////////////////////////////////
  31 #include <SFML/Graphics/Export.hpp>
  32 #include <SFML/Graphics/Drawable.hpp>
  33 #include <SFML/Graphics/Transformable.hpp>
  34 #include <SFML/Graphics/Font.hpp>
  35 #include <SFML/Graphics/Rect.hpp>
  36 #include <SFML/Graphics/VertexArray.hpp>
  37 #include <SFML/System/String.hpp>
  38 #include <string>
  39 #include <vector>
  40
  41
  42 namespace sf
  43 {
  44 ////////////////////////////////////////////////////////////
  45 /// \brief Graphical text that can be drawn to a render target
  46 ///
  47 ////////////////////////////////////////////////////////////
  48 class SFML_GRAPHICS_API Text : public Drawable, public Transformable
  49 {
  50 public:
  51
  52     ////////////////////////////////////////////////////////////
  53     /// \brief Enumeration of the string drawing styles
  54     ///
  55     ////////////////////////////////////////////////////////////
  56     enum Style
  57     {
  58         Regular       = 0,      ///< Regular characters, no style
  59         Bold          = 1 << 0, ///< Bold characters
  60         Italic        = 1 << 1, ///< Italic characters
  61         Underlined    = 1 << 2, ///< Underlined characters
  62         StrikeThrough = 1 << 3  ///< Strike through characters
  63     };
  64
  65     ////////////////////////////////////////////////////////////
  66     /// \brief Default constructor
  67     ///
  68     /// Creates an empty text.
  69     ///
  70     ////////////////////////////////////////////////////////////
  71     Text();
  72
  73     ////////////////////////////////////////////////////////////
  74     /// \brief Construct the text from a string, font and size
  75     ///
  76     /// Note that if the used font is a bitmap font, it is not
  77     /// scalable, thus not all requested sizes will be available
  78     /// to use. This needs to be taken into consideration when
  79     /// setting the character size. If you need to display text
  80     /// of a certain size, make sure the corresponding bitmap
  81     /// font that supports that size is used.
  82     ///
  83     /// \param string         Text assigned to the string
  84     /// \param font           Font used to draw the string
  85     /// \param characterSize  Base size of characters, in pixels
  86     ///
  87     ////////////////////////////////////////////////////////////
  88     Text(const String& string, const Font& font, unsigned int characterSize = 30);
  89
  90     ////////////////////////////////////////////////////////////
  91     /// \brief Set the text's string
  92     ///
  93     /// The \a string argument is a sf::String, which can
  94     /// automatically be constructed from standard string types.
  95     /// So, the following calls are all valid:
  96     /// \code
  97     /// text.setString("hello");
  98     /// text.setString(L"hello");
  99     /// text.setString(std::string("hello"));
 100     /// text.setString(std::wstring(L"hello"));
 101     /// \endcode
 102     /// A text's string is empty by default.
 103     ///
 104     /// \param string New string
 105     ///
 106     /// \see getString
 107     ///
 108     ////////////////////////////////////////////////////////////
 109     void setString(const String& string);
 110
 111     ////////////////////////////////////////////////////////////
 112     /// \brief Set the text's font
 113     ///
 114     /// The \a font argument refers to a font that must
 115     /// exist as long as the text uses it. Indeed, the text
 116     /// doesn't store its own copy of the font, but rather keeps
 117     /// a pointer to the one that you passed to this function.
 118     /// If the font is destroyed and the text tries to
 119     /// use it, the behavior is undefined.
 120     ///
 121     /// \param font New font
 122     ///
 123     /// \see getFont
 124     ///
 125     ////////////////////////////////////////////////////////////
 126     void setFont(const Font& font);
 127
 128     ////////////////////////////////////////////////////////////
 129     /// \brief Set the character size
 130     ///
 131     /// The default size is 30.
 132     ///
 133     /// Note that if the used font is a bitmap font, it is not
 134     /// scalable, thus not all requested sizes will be available
 135     /// to use. This needs to be taken into consideration when
 136     /// setting the character size. If you need to display text
 137     /// of a certain size, make sure the corresponding bitmap
 138     /// font that supports that size is used.
 139     ///
 140     /// \param size New character size, in pixels
 141     ///
 142     /// \see getCharacterSize
 143     ///
 144     ////////////////////////////////////////////////////////////
 145     void setCharacterSize(unsigned int size);
 146
 147     ////////////////////////////////////////////////////////////
 148     /// \brief Set the text's style
 149     ///
 150     /// You can pass a combination of one or more styles, for
 151     /// example sf::Text::Bold | sf::Text::Italic.
 152     /// The default style is sf::Text::Regular.
 153     ///
 154     /// \param style New style
 155     ///
 156     /// \see getStyle
 157     ///
 158     ////////////////////////////////////////////////////////////
 159     void setStyle(Uint32 style);
 160
 161     ////////////////////////////////////////////////////////////
 162     /// \brief Set the global color of the text
 163     ///
 164     /// By default, the text's color is opaque white.
 165     ///
 166     /// \param color New color of the text
 167     ///
 168     /// \see getColor
 169     ///
 170     ////////////////////////////////////////////////////////////
 171     void setColor(const Color& color);
 172
 173     ////////////////////////////////////////////////////////////
 174     /// \brief Get the text's string
 175     ///
 176     /// The returned string is a sf::String, which can automatically
 177     /// be converted to standard string types. So, the following
 178     /// lines of code are all valid:
 179     /// \code
 180     /// sf::String   s1 = text.getString();
 181     /// std::string  s2 = text.getString();
 182     /// std::wstring s3 = text.getString();
 183     /// \endcode
 184     ///
 185     /// \return Text's string
 186     ///
 187     /// \see setString
 188     ///
 189     ////////////////////////////////////////////////////////////
 190     const String& getString() const;
 191
 192     ////////////////////////////////////////////////////////////
 193     /// \brief Get the text's font
 194     ///
 195     /// If the text has no font attached, a NULL pointer is returned.
 196     /// The returned pointer is const, which means that you
 197     /// cannot modify the font when you get it from this function.
 198     ///
 199     /// \return Pointer to the text's font
 200     ///
 201     /// \see setFont
 202     ///
 203     ////////////////////////////////////////////////////////////
 204     const Font* getFont() const;
 205
 206     ////////////////////////////////////////////////////////////
 207     /// \brief Get the character size
 208     ///
 209     /// \return Size of the characters, in pixels
 210     ///
 211     /// \see setCharacterSize
 212     ///
 213     ////////////////////////////////////////////////////////////
 214     unsigned int getCharacterSize() const;
 215
 216     ////////////////////////////////////////////////////////////
 217     /// \brief Get the text's style
 218     ///
 219     /// \return Text's style
 220     ///
 221     /// \see setStyle
 222     ///
 223     ////////////////////////////////////////////////////////////
 224     Uint32 getStyle() const;
 225
 226     ////////////////////////////////////////////////////////////
 227     /// \brief Get the global color of the text
 228     ///
 229     /// \return Global color of the text
 230     ///
 231     /// \see setColor
 232     ///
 233     ////////////////////////////////////////////////////////////
 234     const Color& getColor() const;
 235
 236     ////////////////////////////////////////////////////////////
 237     /// \brief Return the position of the \a index-th character
 238     ///
 239     /// This function computes the visual position of a character
 240     /// from its index in the string. The returned position is
 241     /// in global coordinates (translation, rotation, scale and
 242     /// origin are applied).
 243     /// If \a index is out of range, the position of the end of
 244     /// the string is returned.
 245     ///
 246     /// \param index Index of the character
 247     ///
 248     /// \return Position of the character
 249     ///
 250     ////////////////////////////////////////////////////////////
 251     Vector2f findCharacterPos(std::size_t index) const;
 252
 253     ////////////////////////////////////////////////////////////
 254     /// \brief Get the local bounding rectangle of the entity
 255     ///
 256     /// The returned rectangle is in local coordinates, which means
 257     /// that it ignores the transformations (translation, rotation,
 258     /// scale, ...) that are applied to the entity.
 259     /// In other words, this function returns the bounds of the
 260     /// entity in the entity's coordinate system.
 261     ///
 262     /// \return Local bounding rectangle of the entity
 263     ///
 264     ////////////////////////////////////////////////////////////
 265     FloatRect getLocalBounds() const;
 266
 267     ////////////////////////////////////////////////////////////
 268     /// \brief Get the global bounding rectangle of the entity
 269     ///
 270     /// The returned rectangle is in global coordinates, which means
 271     /// that it takes in account the transformations (translation,
 272     /// rotation, scale, ...) that are applied to the entity.
 273     /// In other words, this function returns the bounds of the
 274     /// sprite in the global 2D world's coordinate system.
 275     ///
 276     /// \return Global bounding rectangle of the entity
 277     ///
 278     ////////////////////////////////////////////////////////////
 279     FloatRect getGlobalBounds() const;
 280
 281 private:
 282
 283     ////////////////////////////////////////////////////////////
 284     /// \brief Draw the text to a render target
 285     ///
 286     /// \param target Render target to draw to
 287     /// \param states Current render states
 288     ///
 289     ////////////////////////////////////////////////////////////
 290     virtual void draw(RenderTarget& target, RenderStates states) const;
 291
 292     ////////////////////////////////////////////////////////////
 293     /// \brief Make sure the text's geometry is updated
 294     ///
 295     /// All the attributes related to rendering are cached, such
 296     /// that the geometry is only updated when necessary.
 297     ///
 298     ////////////////////////////////////////////////////////////
 299     void ensureGeometryUpdate() const;
 300
 301     ////////////////////////////////////////////////////////////
 302     // Member data
 303     ////////////////////////////////////////////////////////////
 304     String              m_string;             ///< String to display
 305     const Font*         m_font;               ///< Font used to display the string
 306     unsigned int        m_characterSize;      ///< Base size of characters, in pixels
 307     Uint32              m_style;              ///< Text style (see Style enum)
 308     Color               m_color;              ///< Text color
 309     mutable VertexArray m_vertices;           ///< Vertex array containing the text's geometry
 310     mutable FloatRect   m_bounds;             ///< Bounding rectangle of the text (in local coordinates)
 311     mutable bool        m_geometryNeedUpdate; ///< Does the geometry need to be recomputed?
 312 };
 313
 314 } // namespace sf
 315
 316
 317 #endif // SFML_TEXT_HPP
 318
 319
 320 ////////////////////////////////////////////////////////////
 321 /// \class sf::Text
 322 /// \ingroup graphics
 323 ///
 324 /// sf::Text is a drawable class that allows to easily display
 325 /// some text with custom style and color on a render target.
 326 ///
 327 /// It inherits all the functions from sf::Transformable:
 328 /// position, rotation, scale, origin. It also adds text-specific
 329 /// properties such as the font to use, the character size,
 330 /// the font style (bold, italic, underlined, strike through), the
 331 /// global color and the text to display of course.
 332 /// It also provides convenience functions to calculate the
 333 /// graphical size of the text, or to get the global position
 334 /// of a given character.
 335 ///
 336 /// sf::Text works in combination with the sf::Font class, which
 337 /// loads and provides the glyphs (visual characters) of a given font.
 338 ///
 339 /// The separation of sf::Font and sf::Text allows more flexibility
 340 /// and better performances: indeed a sf::Font is a heavy resource,
 341 /// and any operation on it is slow (often too slow for real-time
 342 /// applications). On the other side, a sf::Text is a lightweight
 343 /// object which can combine the glyphs data and metrics of a sf::Font
 344 /// to display any text on a render target.
 345 ///
 346 /// It is important to note that the sf::Text instance doesn't
 347 /// copy the font that it uses, it only keeps a reference to it.
 348 /// Thus, a sf::Font must not be destructed while it is
 349 /// used by a sf::Text (i.e. never write a function that
 350 /// uses a local sf::Font instance for creating a text).
 351 ///
 352 /// See also the note on coordinates and undistorted rendering in sf::Transformable.
 353 ///
 354 /// Usage example:
 355 /// \code
 356 /// // Declare and load a font
 357 /// sf::Font font;
 358 /// font.loadFromFile("arial.ttf");
 359 ///
 360 /// // Create a text
 361 /// sf::Text text("hello", font);
 362 /// text.setCharacterSize(30);
 363 /// text.setStyle(sf::Text::Bold);
 364 /// text.setColor(sf::Color::Red);
 365 ///
 366 /// // Draw it
 367 /// window.draw(text);
 368 /// \endcode
 369 ///
 370 /// \see sf::Font, sf::Transformable
 371 ///
 372 ////////////////////////////////////////////////////////////