capi/dali/public-api/text/font.h

   1 #ifndef __DALI_FONT_H__
   2 #define __DALI_FONT_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.0 (the License);
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //     http://floralicense.org/license/
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an AS IS BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19
  20 /**
  21  * @addtogroup CAPI_DALI_TEXT_MODULE
  22  * @{
  23  */
  24
  25 // INTERNAL INCLUDES
  26 #include <dali/public-api/object/base-handle.h>
  27 #include <dali/public-api/text/font-parameters.h>
  28 #include <dali/public-api/text/text.h>
  29
  30 namespace Dali DALI_IMPORT_API
  31 {
  32
  33 struct Vector3;
  34
  35 namespace Internal DALI_INTERNAL
  36 {
  37 class Font;
  38 }
  39
  40 /**
  41  * @brief Encapsulates a font resource.
  42  * Fonts are managed by the font manager, which loads any new fonts requested by applications. The font
  43  * manager keeps a cache of the most recently used fonts, and if a new font is requested when the cache
  44  * is full it will delete an old one (if there is one not in use).
  45  * This font class will request a font from the font manager in a manner which is not visible to the
  46  * application.
  47  *
  48  * Fonts will be created from a font name (like courier or comic) and font size (specified in points).
  49  */
  50 class Font : public BaseHandle
  51 {
  52 public:
  53   /**
  54    * @brief Stores glyph's metrics.
  55    *
  56    * <ul>
  57    *   <li>\e Advance. The distance between the glyph's current pen position and the pen's position of the next glyph.
  58    *   <li>\e Bearing. The horizontal top side bearing. Is the distance between the baseline and the top of the glyph.
  59    *   <li>\e Width.   The glyph's width.
  60    *   <li>\e Height.  The glyph's height.
  61    * </ul>
  62    */
  63   class Metrics
  64   {
  65   public:
  66     /**
  67      * @brief Default constructor.
  68      *
  69      * Creates the implentation instance.
  70      */
  71     Metrics();
  72
  73     /**
  74      * @brief Destructor.
  75      *
  76      * Destroyes the implementaiton instance.
  77      */
  78     virtual ~Metrics();
  79
  80     /**
  81      * @brief Copy constructor.
  82      *
  83      * @param [in] metrics Metrics to be copied.
  84      */
  85     Metrics( const Metrics& metrics );
  86
  87     /**
  88      * @brief Assignment operator.
  89      *
  90      * @param [in] metrics Metrics to be assigned.
  91      * @return a reference to this
  92      */
  93     Metrics& operator=( const Metrics& metrics );
  94
  95     /**
  96      * @brief Retrieves the advance metric.
  97      *
  98      * @return the advance metric.
  99      */
 100     float GetAdvance() const;
 101
 102     /**
 103      * @brief Retrieves the bearing metric.
 104      *
 105      * @return the bearing metric.
 106      */
 107     float GetBearing() const;
 108
 109     /**
 110      * @brief Retrieves the width metric.
 111      *
 112      * @return the width metric.
 113      */
 114     float GetWidth() const;
 115
 116     /**
 117      * @brief Retrieves the height metric.
 118      *
 119      * @return the height metric.
 120      */
 121     float GetHeight() const;
 122
 123   public: // Not intended for application developers
 124     struct Impl;
 125
 126     /**
 127      * @brief Constructor.
 128      *
 129      * Initialization with metrics data.
 130      * @param implementation Glyph's metrics.
 131      */
 132     Metrics( const Impl& implementation );
 133
 134   private:
 135     Impl* mImpl; ///< Implementation.
 136   };
 137
 138 public:
 139   /**
 140    * @brief Create an empty Font.
 141    *
 142    * This can be initialised with Font::New(...)
 143    */
 144   Font();
 145
 146   /**
 147    * @brief Create an initialised Font with the given parameters. If no parameters are given, system defaults are used.
 148    *
 149    * @param [in] fontParameters The font parameters.
 150    * @return A handle to a newly allocated font.
 151    */
 152   static Font New( const FontParameters& fontParameters = DEFAULT_FONT_PARAMETERS );
 153
 154   /**
 155    * @brief Downcast an Object handle to Font handle.
 156    *
 157    * If handle points to a Font object the downcast produces valid
 158    * handle. If not the returned handle is left uninitialized.
 159    *
 160    * @param[in] handle to An object
 161    * @return handle to a Font object or an uninitialized handle
 162    */
 163   static Font DownCast( BaseHandle handle );
 164
 165   /**
 166    * @brief Try to detect font for text.
 167    *
 168    * @param [in] text displayed text
 169    * @return string containing a font name, or an empty string.
 170    */
 171   static const std::string GetFamilyForText(const std::string& text);
 172
 173   /**
 174    * @copydoc GetFamilyForText(const std::string& text)
 175    */
 176   static const std::string GetFamilyForText(const Text& text);
 177
 178   /**
 179    * @brief Try to detect font for character.
 180    *
 181    * @param [in] character displayed character
 182    * @return string containing a font name, or an empty string.
 183    */
 184   static const std::string GetFamilyForText(const Character& character);
 185
 186   /**
 187    * @brief Virtual destructor.
 188    *
 189    * Dali::Object derived classes typically do not contain member data.
 190    */
 191   virtual ~Font();
 192
 193   /**
 194    * @copydoc Dali::BaseHandle::operator=
 195    */
 196   using BaseHandle::operator=;
 197
 198   /**
 199    * @brief Convert a PixelSize from CapsHeight to it's equivalent LineHeight.
 200    *
 201    * @param [in] fontFamily   The family's name of the font requested
 202    * @param [in] fontStyle The style of the font requested.
 203    * @param [in] capsHeight The size of the font ascenders required in pixels
 204    * @return The equivalent LineHeight (baseline to baseline) for the font
 205    */
 206   static PixelSize GetLineHeightFromCapsHeight(const std::string& fontFamily, const std::string& fontStyle, const CapsHeight& capsHeight);
 207
 208   /**
 209    * @brief The mode for GetInstalledFonts()
 210    */
 211   enum FontListMode
 212   {
 213     LIST_SYSTEM_FONTS,                   ///< List system fonts
 214     LIST_APPLICATION_FONTS,              ///< List application fonts
 215     LIST_ALL_FONTS                       ///< List all fonts
 216   };
 217
 218   /**
 219    * @brief Gets the list of available fonts.
 220    *
 221    * @param mode which fonts to include in the list, default is LIST_SYSTEM_FONTS
 222    * @return a list of font family names
 223    */
 224   static std::vector<std::string> GetInstalledFonts( FontListMode mode = LIST_SYSTEM_FONTS );
 225
 226   /**
 227    * @brief Returns the width of the area needed to display some text if the text is textHeightPx pixels high.
 228    *
 229    * Note that the text is not processed in any way before this calculation is performed (no stretching/scaling)
 230    * @param [in] text           The text to measure
 231    * @param [in] textHeightPx   The text height required
 232    * @return                    The displayed width in pixels
 233    */
 234   float MeasureTextWidth(const std::string& text, float textHeightPx) const;
 235
 236   /**
 237    * @copydoc MeasureTextWidth(const std::string& text, float textHeightPx) const
 238    */
 239   float MeasureTextWidth(const Text& text, float textHeightPx) const;
 240
 241   /**
 242    * @brief Returns the width of the area needed to display the character if the text is textHeightPx pixels high.
 243    *
 244    * Note that the character is not processed in any way before this calculation is performed (no stretching/scaling)
 245    * @param [in] character      The character to measure
 246    * @param [in] textHeightPx   The text height required
 247    * @return                    The displayed width in pixels
 248    */
 249   float MeasureTextWidth(const Character& character, float textHeightPx) const;
 250
 251   /**
 252    * @brief Returns the height of the area needed to display the text if the text is textWidthPx pixels wide.
 253    *
 254    * Note that the text is not processed in any way before this calculation is performed (no stretching/scaling)
 255    * @param [in] text           The text to measure
 256    * @param [in] textWidthPx    The text width required
 257    * @return                    The displayed height in pixels
 258    */
 259   float MeasureTextHeight(const std::string& text, float textWidthPx) const;
 260
 261   /**
 262    * @copydoc MeasureTextHeight(const std::string& text, float textWidthPx) const
 263    */
 264   float MeasureTextHeight(const Text& text, float textWidthPx) const;
 265
 266   /**
 267    * @brief Returns the height of the area needed to display the character if the text is textWidthPx pixels wide.
 268    *
 269    * Note that the character is not processed in any way before this calculation is performed (no stretching/scaling)
 270    * @param [in] character      The character to measure
 271    * @param [in] textWidthPx    The text width required
 272    * @return                    The displayed height in pixels
 273    */
 274   float MeasureTextHeight(const Character& character, float textWidthPx) const;
 275
 276   /**
 277    * @brief Measure the natural size of a text string, as displayed in this font.
 278    *
 279    * @param[in] text The text string to measure.
 280    * @return The natural size of the text.
 281    */
 282   Vector3 MeasureText(const std::string& text) const;
 283
 284   /**
 285    * @copydoc MeasureText(const std::string& text) const
 286    */
 287   Vector3 MeasureText(const Text& text) const;
 288
 289   /**
 290    * @brief Measure the natural size of a character, as displayed in this font.
 291    *
 292    * @param[in] character The character to measure.
 293    * @return The natural size of the character.
 294    */
 295   Vector3 MeasureText(const Character& character) const;
 296
 297   /**
 298    * @brief Tells whether text is supported with font.
 299    *
 300    * @param [in] text glyphs to test
 301    * @return true if the glyphs are all supported by the font
 302    */
 303   bool AllGlyphsSupported(const std::string& text) const;
 304
 305   /**
 306    * @copydoc AllGlyphsSupported(const std::string& text) const
 307    * @param [in] text glyphs to test
 308    * @return true if the glyphs are all supported by the font
 309    */
 310   bool AllGlyphsSupported(const Text& text) const;
 311
 312   /**
 313    * @brief Tells whether character is supported with font.
 314    *
 315    * @param [in] character The character to test
 316    * @return true if the glyph is supported by the font
 317    */
 318   bool AllGlyphsSupported(const Character& character) const;
 319
 320   /**
 321    * @brief Retrieves the line height.
 322    *
 323    * The line height is the distance between two consecutive base lines.
 324    * @return The line height.
 325    */
 326   float GetLineHeight() const;
 327
 328   /**
 329    * @brief Retrieves the ascender metric.
 330    *
 331    * The ascender metric is the distance between the base line and the top of the highest character in the font.
 332    * @return The ascender metric.
 333    */
 334   float GetAscender() const;
 335
 336   /**
 337    * @brief Retrieves the underline's thickness.
 338    *
 339    *
 340    * It includes the vertical pad adjust used to add effects like glow or shadow.
 341    *
 342    * @return The underline's thickness.
 343    */
 344   float GetUnderlineThickness() const;
 345
 346   /**
 347    * @brief Retrieves the underline's position.
 348    *
 349    *
 350    * It includes the vertical pad adjust used to add effects like glow or shadow.
 351    *
 352    * @return The underline's position.
 353    */
 354   float GetUnderlinePosition() const;
 355
 356   /**
 357    * @brief Retrieves glyph metrics.
 358    *
 359    * @see Font::Metrics.
 360    * @param [in] character The character which its metrics are going to be retrieved.
 361    * @return The glyph metrics.
 362    */
 363   Metrics GetMetrics(const Character& character) const;
 364
 365   /**
 366    * @brief Retrieves whether this font was created with a default system font.
 367    *
 368    * @return \e true if this font was created as a default system font.
 369    */
 370   bool IsDefaultSystemFont() const;
 371
 372   /**
 373    * @brief Retrieves whether this font was created with a default system size.
 374    *
 375    * @return \e true if this font was created as a default system size.
 376    */
 377   bool IsDefaultSystemSize() const;
 378
 379   /**
 380    * @brief Gets the name of the font's family.
 381    *
 382    * @return The name of the font's family.
 383    */
 384   const std::string& GetName() const;
 385
 386   /**
 387    * @brief Gets the font's style.
 388    *
 389    * @return The font's style.
 390    */
 391   const std::string& GetStyle() const;
 392
 393   /**
 394    * @brief Return font size in points.
 395    *
 396    * @return size in points
 397    */
 398   float GetPointSize() const;
 399
 400   /**
 401    * @brief Return font size in pixels.
 402    *
 403    * @return size in pixels
 404    */
 405   unsigned int GetPixelSize() const;
 406
 407   /**
 408    * @brief Retrieves the size of the font in pixels from a given size in points.
 409    *
 410    * @param[in] pointSize Size of the font in points.
 411    * @return size of the font in pixels.
 412    */
 413   static unsigned int PointsToPixels( float pointSize );
 414
 415   /**
 416    * @brief Retrieves the size of the font in points from a given size in pixels
 417    * @param[in] pixelsSize Size of the font in pixels.
 418    *
 419    * @return size of the font in points.
 420    */
 421   static float PixelsToPoints( unsigned int pixelsSize );
 422
 423 public: // Not intended for application developers
 424
 425   /**
 426    * @brief This constructor is used by Dali New() methods
 427    *
 428    * @param [in] font A pointer to a newly allocated Dali resource
 429    */
 430   explicit DALI_INTERNAL Font(Internal::Font* font);
 431 };
 432
 433 } // namespace Dali
 434
 435 /**
 436  * @}
 437  */
 438 #endif // __DALI_FONT_H__