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 Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
  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 // INTERNAL INCLUDES
  22 #include <dali/public-api/object/base-handle.h>
  23 #include <dali/public-api/text/font-parameters.h>
  24 #include <dali/public-api/text/text.h>
  25
  26 namespace Dali DALI_IMPORT_API
  27 {
  28
  29 struct Vector3;
  30
  31 namespace Internal DALI_INTERNAL
  32 {
  33 class Font;
  34 }
  35
  36 /**
  37  * @brief Encapsulates a font resource.
  38  * Fonts are managed by the font manager, which loads any new fonts requested by applications. The font
  39  * manager keeps a cache of the most recently used fonts, and if a new font is requested when the cache
  40  * is full it will delete an old one (if there is one not in use).
  41  * This font class will request a font from the font manager in a manner which is not visible to the
  42  * application.
  43  *
  44  * Fonts will be created from a font name (like courier or comic) and font size (specified in points).
  45  */
  46 class Font : public BaseHandle
  47 {
  48 public:
  49   /**
  50    * @brief Stores glyph's metrics.
  51    *
  52    * <ul>
  53    *   <li>\e Advance. The distance between the glyph's current pen position and the pen's position of the next glyph.
  54    *   <li>\e Bearing. The horizontal top side bearing. Is the distance between the baseline and the top of the glyph.
  55    *   <li>\e Width.   The glyph's width.
  56    *   <li>\e Height.  The glyph's height.
  57    * </ul>
  58    */
  59   class Metrics
  60   {
  61   public:
  62     /**
  63      * @brief Default constructor.
  64      *
  65      * Creates the implentation instance.
  66      */
  67     Metrics();
  68
  69     /**
  70      * @brief Destructor.
  71      *
  72      * Destroyes the implementaiton instance.
  73      */
  74     virtual ~Metrics();
  75
  76     /**
  77      * @brief Copy constructor.
  78      *
  79      * @param [in] metrics Metrics to be copied.
  80      */
  81     Metrics( const Metrics& metrics );
  82
  83     /**
  84      * @brief Assignment operator.
  85      *
  86      * @param [in] metrics Metrics to be assigned.
  87      * @return a reference to this
  88      */
  89     Metrics& operator=( const Metrics& metrics );
  90
  91     /**
  92      * @brief Retrieves the advance metric.
  93      *
  94      * @return the advance metric.
  95      */
  96     float GetAdvance() const;
  97
  98     /**
  99      * @brief Retrieves the bearing metric.
 100      *
 101      * @return the bearing metric.
 102      */
 103     float GetBearing() const;
 104
 105     /**
 106      * @brief Retrieves the width metric.
 107      *
 108      * @return the width metric.
 109      */
 110     float GetWidth() const;
 111
 112     /**
 113      * @brief Retrieves the height metric.
 114      *
 115      * @return the height metric.
 116      */
 117     float GetHeight() const;
 118
 119   public: // Not intended for application developers
 120     struct Impl;
 121
 122     /**
 123      * @brief Constructor.
 124      *
 125      * Initialization with metrics data.
 126      * @param implementation Glyph's metrics.
 127      */
 128     Metrics( const Impl& implementation );
 129
 130   private:
 131     Impl* mImpl; ///< Implementation.
 132   };
 133
 134 public:
 135   /**
 136    * @brief Create an empty Font.
 137    *
 138    * This can be initialised with Font::New(...)
 139    */
 140   Font();
 141
 142   /**
 143    * @brief Create an initialised Font with the given parameters. If no parameters are given, system defaults are used.
 144    *
 145    * @param [in] fontParameters The font parameters.
 146    * @return A handle to a newly allocated font.
 147    */
 148   static Font New( const FontParameters& fontParameters = DEFAULT_FONT_PARAMETERS );
 149
 150   /**
 151    * @brief Downcast an Object handle to Font handle.
 152    *
 153    * If handle points to a Font object the downcast produces valid
 154    * handle. If not the returned handle is left uninitialized.
 155    *
 156    * @param[in] handle to An object
 157    * @return handle to a Font object or an uninitialized handle
 158    */
 159   static Font DownCast( BaseHandle handle );
 160
 161   /**
 162    * @brief Try to detect font for text.
 163    *
 164    * @param [in] text displayed text
 165    * @return string containing a font name, or an empty string.
 166    */
 167   static const std::string GetFamilyForText(const Text& text);
 168
 169   /**
 170    * @brief Destructor
 171    *
 172    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 173    */
 174   ~Font();
 175
 176   /**
 177    * @copydoc Dali::BaseHandle::operator=
 178    */
 179   using BaseHandle::operator=;
 180
 181   /**
 182    * @brief Convert a PixelSize from CapsHeight to it's equivalent LineHeight.
 183    *
 184    * @param [in] fontFamily   The family's name of the font requested
 185    * @param [in] fontStyle The style of the font requested.
 186    * @param [in] capsHeight The size of the font ascenders required in pixels
 187    * @return The equivalent LineHeight (baseline to baseline) for the font
 188    */
 189   static PixelSize GetLineHeightFromCapsHeight(const std::string& fontFamily, const std::string& fontStyle, const CapsHeight& capsHeight);
 190
 191   /**
 192    * @brief The mode for GetInstalledFonts()
 193    */
 194   enum FontListMode
 195   {
 196     LIST_SYSTEM_FONTS,                   ///< List system fonts
 197     LIST_APPLICATION_FONTS,              ///< List application fonts
 198     LIST_ALL_FONTS                       ///< List all fonts
 199   };
 200
 201   /**
 202    * @brief Gets the list of available fonts.
 203    *
 204    * @param mode which fonts to include in the list, default is LIST_SYSTEM_FONTS
 205    * @return a list of font family names
 206    */
 207   static std::vector<std::string> GetInstalledFonts( FontListMode mode = LIST_SYSTEM_FONTS );
 208
 209   /**
 210    * @brief Returns the width of the area needed to display some text if the text is textHeightPx pixels high.
 211    *
 212    * Note that the text is not processed in any way before this calculation is performed (no stretching/scaling)
 213    * @param [in] text           The text to measure
 214    * @param [in] textHeightPx   The text height required
 215    * @return                    The displayed width in pixels
 216    */
 217   float MeasureTextWidth(const Text& text, float textHeightPx) const;
 218
 219   /**
 220    * @brief Returns the height of the area needed to display the text if the text is textWidthPx pixels wide.
 221    *
 222    * Note that the text is not processed in any way before this calculation is performed (no stretching/scaling)
 223    * @param [in] text           The text to measure
 224    * @param [in] textWidthPx    The text width required
 225    * @return                    The displayed height in pixels
 226    */
 227   float MeasureTextHeight(const Text& text, float textWidthPx) const;
 228
 229   /**
 230    * @brief Measure the natural size of a text string, as displayed in this font.
 231    *
 232    * @param[in] text The text string to measure.
 233    * @return The natural size of the text.
 234    */
 235   Vector3 MeasureText(const Text& text) const;
 236
 237   /**
 238    * @brief Tells whether text is supported with font.
 239    *
 240    * @param [in] text glyphs to test
 241    * @return true if the glyphs are all supported by the font
 242    */
 243   bool AllGlyphsSupported(const Text& text) const;
 244
 245   /**
 246    * @brief Retrieves the line height.
 247    *
 248    * The line height is the distance between two consecutive base lines.
 249    * @return The line height.
 250    */
 251   float GetLineHeight() const;
 252
 253   /**
 254    * @brief Retrieves the ascender metric.
 255    *
 256    * The ascender metric is the distance between the base line and the top of the highest character in the font.
 257    * @return The ascender metric.
 258    */
 259   float GetAscender() const;
 260
 261   /**
 262    * @brief Retrieves the underline's thickness.
 263    *
 264    *
 265    * It includes the vertical pad adjust used to add effects like glow or shadow.
 266    *
 267    * @return The underline's thickness.
 268    */
 269   float GetUnderlineThickness() const;
 270
 271   /**
 272    * @brief Retrieves the underline's position.
 273    *
 274    *
 275    * It includes the vertical pad adjust used to add effects like glow or shadow.
 276    *
 277    * @return The underline's position.
 278    */
 279   float GetUnderlinePosition() const;
 280
 281   /**
 282    * @brief Retrieves glyph metrics.
 283    *
 284    * @see Font::Metrics.
 285    * @param [in] character The character which its metrics are going to be retrieved.
 286    * @return The glyph metrics.
 287    */
 288   Metrics GetMetrics(const Character& character) const;
 289
 290   /**
 291    * @brief Retrieves whether this font was created with a default system font.
 292    *
 293    * @return \e true if this font was created as a default system font.
 294    */
 295   bool IsDefaultSystemFont() const;
 296
 297   /**
 298    * @brief Retrieves whether this font was created with a default system size.
 299    *
 300    * @return \e true if this font was created as a default system size.
 301    */
 302   bool IsDefaultSystemSize() const;
 303
 304   /**
 305    * @brief Gets the name of the font's family.
 306    *
 307    * @return The name of the font's family.
 308    */
 309   const std::string& GetName() const;
 310
 311   /**
 312    * @brief Gets the font's style.
 313    *
 314    * @return The font's style.
 315    */
 316   const std::string& GetStyle() const;
 317
 318   /**
 319    * @brief Return font size in points.
 320    *
 321    * @return size in points
 322    */
 323   float GetPointSize() const;
 324
 325   /**
 326    * @brief Return font size in pixels.
 327    *
 328    * @return size in pixels
 329    */
 330   unsigned int GetPixelSize() const;
 331
 332   /**
 333    * @brief Retrieves the size of the font in pixels from a given size in points.
 334    *
 335    * @param[in] pointSize Size of the font in points.
 336    * @return size of the font in pixels.
 337    */
 338   static unsigned int PointsToPixels( float pointSize );
 339
 340   /**
 341    * @brief Retrieves the size of the font in points from a given size in pixels
 342    * @param[in] pixelsSize Size of the font in pixels.
 343    *
 344    * @return size of the font in points.
 345    */
 346   static float PixelsToPoints( unsigned int pixelsSize );
 347
 348 public: // Not intended for application developers
 349
 350   /**
 351    * @brief This constructor is used by Dali New() methods
 352    *
 353    * @param [in] font A pointer to a newly allocated Dali resource
 354    */
 355   explicit DALI_INTERNAL Font(Internal::Font* font);
 356 };
 357
 358 } // namespace Dali
 359
 360 #endif // __DALI_FONT_H__