gfx/src/nsFontMetrics.h

   1 /* -*- Mode: C++; tab-width: 20; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef NSFONTMETRICS__H__
   7 #define NSFONTMETRICS__H__
   8
   9 #include <stdint.h>              // for uint32_t
  10 #include <sys/types.h>           // for int32_t
  11 #include "mozilla/Assertions.h"  // for MOZ_ASSERT_HELPER2
  12 #include "mozilla/RefPtr.h"      // for RefPtr
  13 #include "nsCOMPtr.h"            // for nsCOMPtr
  14 #include "nsCoord.h"             // for nscoord
  15 #include "nsError.h"             // for nsresult
  16 #include "nsFont.h"              // for nsFont
  17 #include "nsISupports.h"         // for NS_INLINE_DECL_REFCOUNTING
  18 #include "nsStyleConsts.h"
  19 #include "nscore.h"  // for char16_t
  20
  21 class gfxContext;
  22 class gfxFontGroup;
  23 class gfxUserFontSet;
  24 class gfxTextPerfMetrics;
  25 class nsPresContext;
  26 class nsAtom;
  27 struct nsBoundingMetrics;
  28
  29 namespace mozilla {
  30 namespace gfx {
  31 class DrawTarget;
  32 }  // namespace gfx
  33 }  // namespace mozilla
  34
  35 /**
  36  * Font metrics
  37  *
  38  * This class may be somewhat misnamed. A better name might be
  39  * nsFontList. The style system uses the nsFont struct for various
  40  * font properties, one of which is font-family, which can contain a
  41  * *list* of font names. The nsFont struct is "realized" by asking the
  42  * pres context to cough up an nsFontMetrics object, which contains
  43  * a list of real font handles, one for each font mentioned in
  44  * font-family (and for each fallback when we fall off the end of that
  45  * list).
  46  *
  47  * The style system needs to have access to certain metrics, such as
  48  * the em height (for the CSS "em" unit), and we use the first Western
  49  * font's metrics for that purpose. The platform-specific
  50  * implementations are expected to select non-Western fonts that "fit"
  51  * reasonably well with the Western font that is loaded at Init time.
  52  */
  53 class nsFontMetrics final {
  54  public:
  55   typedef mozilla::gfx::DrawTarget DrawTarget;
  56
  57   enum FontOrientation { eHorizontal, eVertical };
  58
  59   struct MOZ_STACK_CLASS Params {
  60     nsAtom* language = nullptr;
  61     bool explicitLanguage = false;
  62     FontOrientation orientation = eHorizontal;
  63     gfxUserFontSet* userFontSet = nullptr;
  64     gfxTextPerfMetrics* textPerf = nullptr;
  65     gfxFontFeatureValueSet* featureValueLookup = nullptr;
  66   };
  67
  68   nsFontMetrics(const nsFont& aFont, const Params& aParams,
  69                 nsPresContext* aContext);
  70
  71   // Used by stylo
  72   NS_INLINE_DECL_THREADSAFE_REFCOUNTING(nsFontMetrics)
  73
  74   /**
  75    * Destroy this font metrics. This breaks the association between
  76    * the font metrics and the pres context.
  77    */
  78   void Destroy();
  79
  80   /**
  81    * Return the font's x-height.
  82    */
  83   nscoord XHeight();
  84
  85   /**
  86    * Return the font's cap-height.
  87    */
  88   nscoord CapHeight();
  89
  90   /**
  91    * Return the font's superscript offset (the distance from the
  92    * baseline to where a superscript's baseline should be placed).
  93    * The value returned will be positive.
  94    */
  95   nscoord SuperscriptOffset();
  96
  97   /**
  98    * Return the font's subscript offset (the distance from the
  99    * baseline to where a subscript's baseline should be placed).
 100    * The value returned will be positive.
 101    */
 102   nscoord SubscriptOffset();
 103
 104   /**
 105    * Return the font's strikeout offset (the distance from the
 106    * baseline to where a strikeout should be placed) and size.
 107    * Positive values are above the baseline, negative below.
 108    */
 109   void GetStrikeout(nscoord& aOffset, nscoord& aSize);
 110
 111   /**
 112    * Return the font's underline offset (the distance from the
 113    * baseline to where a underline should be placed) and size.
 114    * Positive values are above the baseline, negative below.
 115    */
 116   void GetUnderline(nscoord& aOffset, nscoord& aSize);
 117
 118   /**
 119    * Returns the amount of internal leading for the font.
 120    * This is normally the difference between the max ascent
 121    * and the em ascent.
 122    */
 123   nscoord InternalLeading();
 124
 125   /**
 126    * Returns the amount of external leading for the font.
 127    * em ascent(?) plus external leading is the font designer's
 128    * recommended line-height for this font.
 129    */
 130   nscoord ExternalLeading();
 131
 132   /**
 133    * Returns the height of the em square.
 134    * This is em ascent plus em descent.
 135    */
 136   nscoord EmHeight();
 137
 138   /**
 139    * Returns the ascent part of the em square.
 140    */
 141   nscoord EmAscent();
 142
 143   /**
 144    * Returns the descent part of the em square.
 145    */
 146   nscoord EmDescent();
 147
 148   /**
 149    * Returns the height of the bounding box.
 150    * This is max ascent plus max descent.
 151    */
 152   nscoord MaxHeight();
 153
 154   /**
 155    * Returns the maximum distance characters in this font extend
 156    * above the base line.
 157    */
 158   nscoord MaxAscent();
 159
 160   /**
 161    * Returns the maximum distance characters in this font extend
 162    * below the base line.
 163    */
 164   nscoord MaxDescent();
 165
 166   /**
 167    * Returns the maximum character advance for the font.
 168    */
 169   nscoord MaxAdvance();
 170
 171   /**
 172    * Returns the average character width
 173    */
 174   nscoord AveCharWidth();
 175
 176   /**
 177    * Returns the often needed width of the space character
 178    */
 179   nscoord SpaceWidth();
 180
 181   /**
 182    * Returns the font associated with these metrics. The return value
 183    * is only defined after Init() has been called.
 184    */
 185   const nsFont& Font() const { return mFont; }
 186
 187   /**
 188    * Returns the language associated with these metrics
 189    */
 190   nsAtom* Language() const { return mLanguage; }
 191
 192   /**
 193    * Returns the orientation (horizontal/vertical) of these metrics.
 194    */
 195   FontOrientation Orientation() const { return mOrientation; }
 196
 197   int32_t GetMaxStringLength();
 198
 199   // Get the width for this string.  aWidth will be updated with the
 200   // width in points, not twips.  Callers must convert it if they
 201   // want it in another format.
 202   nscoord GetWidth(const char* aString, uint32_t aLength,
 203                    DrawTarget* aDrawTarget);
 204   nscoord GetWidth(const char16_t* aString, uint32_t aLength,
 205                    DrawTarget* aDrawTarget);
 206
 207   // Draw a string using this font handle on the surface passed in.
 208   void DrawString(const char* aString, uint32_t aLength, nscoord aX, nscoord aY,
 209                   gfxContext* aContext);
 210   void DrawString(const char16_t* aString, uint32_t aLength, nscoord aX,
 211                   nscoord aY, gfxContext* aContext,
 212                   DrawTarget* aTextRunConstructionDrawTarget);
 213
 214   nsBoundingMetrics GetBoundingMetrics(const char16_t* aString,
 215                                        uint32_t aLength,
 216                                        DrawTarget* aDrawTarget);
 217
 218   // Returns the LOOSE_INK_EXTENTS bounds of the text for determing the
 219   // overflow area of the string.
 220   nsBoundingMetrics GetInkBoundsForInkOverflow(const char16_t* aString,
 221                                                uint32_t aLength,
 222                                                DrawTarget* aDrawTarget);
 223
 224   void SetTextRunRTL(bool aIsRTL) { mTextRunRTL = aIsRTL; }
 225   bool GetTextRunRTL() const { return mTextRunRTL; }
 226
 227   void SetVertical(bool aVertical) { mVertical = aVertical; }
 228   bool GetVertical() const { return mVertical; }
 229
 230   void SetTextOrientation(mozilla::StyleTextOrientation aTextOrientation) {
 231     mTextOrientation = aTextOrientation;
 232   }
 233   mozilla::StyleTextOrientation GetTextOrientation() const {
 234     return mTextOrientation;
 235   }
 236
 237   bool ExplicitLanguage() const { return mExplicitLanguage; }
 238
 239   gfxFontGroup* GetThebesFontGroup() const { return mFontGroup; }
 240   gfxUserFontSet* GetUserFontSet() const;
 241
 242   int32_t AppUnitsPerDevPixel() const { return mP2A; }
 243
 244  private:
 245   // Private destructor, to discourage deletion outside of Release():
 246   ~nsFontMetrics();
 247
 248   nsFont mFont;
 249   RefPtr<gfxFontGroup> mFontGroup;
 250   RefPtr<nsAtom> mLanguage;
 251   // Pointer to the pres context for which this fontMetrics object was
 252   // created.
 253   nsPresContext* MOZ_NON_OWNING_REF mPresContext;
 254   int32_t mP2A;
 255
 256   // The font orientation (horizontal or vertical) for which these metrics
 257   // have been initialized. This determines which line metrics (ascent and
 258   // descent) they will return.
 259   FontOrientation mOrientation;
 260
 261   // Whether mLanguage comes from explicit markup (in which case it should be
 262   // used to tailor effects like case-conversion) or is an inferred/default
 263   // value.
 264   bool mExplicitLanguage;
 265
 266   // These fields may be set by clients to control the behavior of methods
 267   // like GetWidth and DrawString according to the writing mode, direction
 268   // and text-orientation desired.
 269   bool mTextRunRTL;
 270   bool mVertical;
 271   mozilla::StyleTextOrientation mTextOrientation;
 272 };
 273
 274 #endif /* NSFONTMETRICS__H__ */