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() const;
  84
  85   /**
  86    * Return the font's cap-height.
  87    */
  88   nscoord CapHeight() const;
  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() const;
  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() const;
 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) const;
 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) const;
 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() const;
 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() const;
 131
 132   /**
 133    * Returns the height of the em square.
 134    * This is em ascent plus em descent.
 135    */
 136   nscoord EmHeight() const;
 137
 138   /**
 139    * Returns the ascent part of the em square.
 140    */
 141   nscoord EmAscent() const;
 142
 143   /**
 144    * Returns the descent part of the em square.
 145    */
 146   nscoord EmDescent() const;
 147
 148   /**
 149    * Returns the height of the bounding box.
 150    * This is max ascent plus max descent.
 151    */
 152   nscoord MaxHeight() const;
 153
 154   /**
 155    * Returns the maximum distance characters in this font extend
 156    * above the base line.
 157    */
 158   nscoord MaxAscent() const;
 159
 160   /**
 161    * Returns the maximum distance characters in this font extend
 162    * below the base line.
 163    */
 164   nscoord MaxDescent() const;
 165
 166   /**
 167    * Returns the maximum character advance for the font.
 168    */
 169   nscoord MaxAdvance() const;
 170
 171   /**
 172    * Returns the average character width
 173    */
 174   nscoord AveCharWidth() const;
 175
 176   /**
 177    * Returns width of the zero character, or AveCharWidth if no zero present.
 178    */
 179   nscoord ZeroOrAveCharWidth() const;
 180
 181   /**
 182    * Returns the often needed width of the space character
 183    */
 184   nscoord SpaceWidth() const;
 185
 186   /**
 187    * Returns the font associated with these metrics. The return value
 188    * is only defined after Init() has been called.
 189    */
 190   const nsFont& Font() const { return mFont; }
 191
 192   /**
 193    * Returns the language associated with these metrics
 194    */
 195   nsAtom* Language() const { return mLanguage; }
 196
 197   /**
 198    * Returns the orientation (horizontal/vertical) of these metrics.
 199    */
 200   FontOrientation Orientation() const { return mOrientation; }
 201
 202   int32_t GetMaxStringLength() const;
 203
 204   // Get the width for this string.  aWidth will be updated with the
 205   // width in points, not twips.  Callers must convert it if they
 206   // want it in another format.
 207   nscoord GetWidth(const char* aString, uint32_t aLength,
 208                    DrawTarget* aDrawTarget) const;
 209   nscoord GetWidth(const char16_t* aString, uint32_t aLength,
 210                    DrawTarget* aDrawTarget) const;
 211
 212   // Draw a string using this font handle on the surface passed in.
 213   void DrawString(const char* aString, uint32_t aLength, nscoord aX, nscoord aY,
 214                   gfxContext* aContext) const;
 215   void DrawString(const char16_t* aString, uint32_t aLength, nscoord aX,
 216                   nscoord aY, gfxContext* aContext,
 217                   DrawTarget* aTextRunConstructionDrawTarget) const;
 218
 219   nsBoundingMetrics GetBoundingMetrics(const char16_t* aString,
 220                                        uint32_t aLength,
 221                                        DrawTarget* aDrawTarget) const;
 222
 223   // Returns the LOOSE_INK_EXTENTS bounds of the text for determing the
 224   // overflow area of the string.
 225   nsBoundingMetrics GetInkBoundsForInkOverflow(const char16_t* aString,
 226                                                uint32_t aLength,
 227                                                DrawTarget* aDrawTarget) const;
 228
 229   void SetTextRunRTL(bool aIsRTL) { mTextRunRTL = aIsRTL; }
 230   bool GetTextRunRTL() const { return mTextRunRTL; }
 231
 232   void SetVertical(bool aVertical) { mVertical = aVertical; }
 233   bool GetVertical() const { return mVertical; }
 234
 235   void SetTextOrientation(mozilla::StyleTextOrientation aTextOrientation) {
 236     mTextOrientation = aTextOrientation;
 237   }
 238   mozilla::StyleTextOrientation GetTextOrientation() const {
 239     return mTextOrientation;
 240   }
 241
 242   bool ExplicitLanguage() const { return mExplicitLanguage; }
 243
 244   gfxFontGroup* GetThebesFontGroup() const { return mFontGroup; }
 245   gfxUserFontSet* GetUserFontSet() const;
 246
 247   int32_t AppUnitsPerDevPixel() const { return mP2A; }
 248
 249  private:
 250   // Private destructor, to discourage deletion outside of Release():
 251   ~nsFontMetrics();
 252
 253   const nsFont mFont;
 254   RefPtr<gfxFontGroup> mFontGroup;
 255   RefPtr<nsAtom> const mLanguage;
 256   // Pointer to the pres context for which this fontMetrics object was
 257   // created.
 258   nsPresContext* MOZ_NON_OWNING_REF mPresContext;
 259   const int32_t mP2A;
 260
 261   // The font orientation (horizontal or vertical) for which these metrics
 262   // have been initialized. This determines which line metrics (ascent and
 263   // descent) they will return.
 264   const FontOrientation mOrientation;
 265
 266   // Whether mLanguage comes from explicit markup (in which case it should be
 267   // used to tailor effects like case-conversion) or is an inferred/default
 268   // value.
 269   const bool mExplicitLanguage;
 270
 271   // These fields may be set by clients to control the behavior of methods
 272   // like GetWidth and DrawString according to the writing mode, direction
 273   // and text-orientation desired.
 274   bool mTextRunRTL;
 275   bool mVertical;
 276   mozilla::StyleTextOrientation mTextOrientation;
 277 };
 278
 279 #endif /* NSFONTMETRICS__H__ */