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
  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 DALI_IMPORT_API 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    * @brief This copy constructor is required for (smart) pointer semantics.
 178    *
 179    * @param [in] handle A reference to the copied handle
 180    */
 181   Font(const Font& handle);
 182
 183   /**
 184    * @brief This assignment operator is required for (smart) pointer semantics.
 185    *
 186    * @param [in] rhs  A reference to the copied handle
 187    * @return A reference to this
 188    */
 189   Font& operator=(const Font& rhs);
 190
 191   /**
 192    * @brief Convert a PixelSize from CapsHeight to it's equivalent LineHeight.
 193    *
 194    * @param [in] fontFamily   The family's name of the font requested
 195    * @param [in] fontStyle The style of the font requested.
 196    * @param [in] capsHeight The size of the font ascenders required in pixels
 197    * @return The equivalent LineHeight (baseline to baseline) for the font
 198    */
 199   static PixelSize GetLineHeightFromCapsHeight(const std::string& fontFamily, const std::string& fontStyle, const CapsHeight& capsHeight);
 200
 201   /**
 202    * @brief The mode for GetInstalledFonts()
 203    */
 204   enum FontListMode
 205   {
 206     LIST_SYSTEM_FONTS,                   ///< List system fonts
 207     LIST_APPLICATION_FONTS,              ///< List application fonts
 208     LIST_ALL_FONTS                       ///< List all fonts
 209   };
 210
 211   /**
 212    * @brief Gets the list of available fonts.
 213    *
 214    * @param mode which fonts to include in the list, default is LIST_SYSTEM_FONTS
 215    * @return a list of font family names
 216    */
 217   static std::vector<std::string> GetInstalledFonts( FontListMode mode = LIST_SYSTEM_FONTS );
 218
 219   /**
 220    * @brief Returns the width of the area needed to display some text if the text is textHeightPx pixels high.
 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] textHeightPx   The text height required
 225    * @return                    The displayed width in pixels
 226    */
 227   float MeasureTextWidth(const Text& text, float textHeightPx) const;
 228
 229   /**
 230    * @brief Returns the height of the area needed to display the text if the text is textWidthPx pixels wide.
 231    *
 232    * Note that the text is not processed in any way before this calculation is performed (no stretching/scaling)
 233    * @param [in] text           The text to measure
 234    * @param [in] textWidthPx    The text width required
 235    * @return                    The displayed height in pixels
 236    */
 237   float MeasureTextHeight(const Text& text, float textWidthPx) const;
 238
 239   /**
 240    * @brief Measure the natural size of a text string, as displayed in this font.
 241    *
 242    * @param[in] text The text string to measure.
 243    * @return The natural size of the text.
 244    */
 245   Vector3 MeasureText(const Text& text) const;
 246
 247   /**
 248    * @brief Tells whether text is supported with font.
 249    *
 250    * @param [in] text glyphs to test
 251    * @return true if the glyphs are all supported by the font
 252    */
 253   bool AllGlyphsSupported(const Text& text) const;
 254
 255   /**
 256    * @brief Retrieves the line height.
 257    *
 258    * The line height is the distance between two consecutive base lines.
 259    * @return The line height.
 260    */
 261   float GetLineHeight() const;
 262
 263   /**
 264    * @brief Retrieves the ascender metric.
 265    *
 266    * The ascender metric is the distance between the base line and the top of the highest character in the font.
 267    * @return The ascender metric.
 268    */
 269   float GetAscender() const;
 270
 271   /**
 272    * @brief Retrieves the underline's thickness.
 273    *
 274    *
 275    * It includes the vertical pad adjust used to add effects like glow or shadow.
 276    *
 277    * @return The underline's thickness.
 278    */
 279   float GetUnderlineThickness() const;
 280
 281   /**
 282    * @brief Retrieves the underline's position.
 283    *
 284    *
 285    * It includes the vertical pad adjust used to add effects like glow or shadow.
 286    *
 287    * @return The underline's position.
 288    */
 289   float GetUnderlinePosition() const;
 290
 291   /**
 292    * @brief Retrieves glyph metrics.
 293    *
 294    * @see Font::Metrics.
 295    * @param [in] character The character which its metrics are going to be retrieved.
 296    * @return The glyph metrics.
 297    */
 298   Metrics GetMetrics(const Character& character) const;
 299
 300   /**
 301    * @brief Retrieves whether this font was created with a default system font.
 302    *
 303    * @return \e true if this font was created as a default system font.
 304    */
 305   bool IsDefaultSystemFont() const;
 306
 307   /**
 308    * @brief Retrieves whether this font was created with a default system size.
 309    *
 310    * @return \e true if this font was created as a default system size.
 311    */
 312   bool IsDefaultSystemSize() const;
 313
 314   /**
 315    * @brief Gets the name of the font's family.
 316    *
 317    * @return The name of the font's family.
 318    */
 319   const std::string& GetName() const;
 320
 321   /**
 322    * @brief Gets the font's style.
 323    *
 324    * @return The font's style.
 325    */
 326   const std::string& GetStyle() const;
 327
 328   /**
 329    * @brief Return font size in points.
 330    *
 331    * @return size in points
 332    */
 333   float GetPointSize() const;
 334
 335   /**
 336    * @brief Return font size in pixels.
 337    *
 338    * @return size in pixels
 339    */
 340   unsigned int GetPixelSize() const;
 341
 342   /**
 343    * @brief Retrieves the size of the font in pixels from a given size in points.
 344    *
 345    * @param[in] pointSize Size of the font in points.
 346    * @return size of the font in pixels.
 347    */
 348   static unsigned int PointsToPixels( float pointSize );
 349
 350   /**
 351    * @brief Retrieves the size of the font in points from a given size in pixels
 352    * @param[in] pixelsSize Size of the font in pixels.
 353    *
 354    * @return size of the font in points.
 355    */
 356   static float PixelsToPoints( unsigned int pixelsSize );
 357
 358 public: // Not intended for application developers
 359
 360   /**
 361    * @brief This constructor is used by Dali New() methods
 362    *
 363    * @param [in] font A pointer to a newly allocated Dali resource
 364    */
 365   explicit DALI_INTERNAL Font(Internal::Font* font);
 366 };
 367
 368 } // namespace Dali
 369
 370 #endif // __DALI_FONT_H__