gfx/src/nsFontMetrics.h

   1 /* -*- Mode: C++; tab-width: 20; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   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 "gfxFont.h"                    // for gfxFont, gfxFontGroup
  12 #include "mozilla/Assertions.h"         // for MOZ_ASSERT_HELPER2
  13 #include "nsAutoPtr.h"                  // for nsRefPtr
  14 #include "nsCOMPtr.h"                   // for nsCOMPtr
  15 #include "nsCoord.h"                    // for nscoord
  16 #include "nsError.h"                    // for nsresult
  17 #include "nsFont.h"                     // for nsFont
  18 #include "nsISupports.h"                // for NS_INLINE_DECL_REFCOUNTING
  19 #include "nscore.h"                     // for char16_t
  20
  21 class gfxUserFontSet;
  22 class gfxTextPerfMetrics;
  23 class nsDeviceContext;
  24 class nsIAtom;
  25 class nsRenderingContext;
  26 struct nsBoundingMetrics;
  27
  28 /**
  29  * Font metrics
  30  *
  31  * This class may be somewhat misnamed. A better name might be
  32  * nsFontList. The style system uses the nsFont struct for various
  33  * font properties, one of which is font-family, which can contain a
  34  * *list* of font names. The nsFont struct is "realized" by asking the
  35  * device context to cough up an nsFontMetrics object, which contains
  36  * a list of real font handles, one for each font mentioned in
  37  * font-family (and for each fallback when we fall off the end of that
  38  * list).
  39  *
  40  * The style system needs to have access to certain metrics, such as
  41  * the em height (for the CSS "em" unit), and we use the first Western
  42  * font's metrics for that purpose. The platform-specific
  43  * implementations are expected to select non-Western fonts that "fit"
  44  * reasonably well with the Western font that is loaded at Init time.
  45  */
  46 class nsFontMetrics MOZ_FINAL
  47 {
  48 public:
  49     nsFontMetrics();
  50
  51     NS_INLINE_DECL_REFCOUNTING(nsFontMetrics)
  52
  53     /**
  54      * Initialize the font metrics. Call this after creating the font metrics.
  55      * Font metrics you get from the font cache do NOT need to be initialized
  56      *
  57      * @see nsDeviceContext#GetMetricsFor()
  58      */
  59     nsresult Init(const nsFont& aFont, nsIAtom* aLanguage,
  60                   nsDeviceContext *aContext,
  61                   gfxUserFontSet *aUserFontSet,
  62                   gfxTextPerfMetrics *aTextPerf);
  63
  64     /**
  65      * Destroy this font metrics. This breaks the association between
  66      * the font metrics and the device context.
  67      */
  68     void Destroy();
  69
  70     /**
  71      * Return the font's x-height.
  72      */
  73     nscoord XHeight();
  74
  75     /**
  76      * Return the font's superscript offset (the distance from the
  77      * baseline to where a superscript's baseline should be placed).
  78      * The value returned will be positive.
  79      */
  80     nscoord SuperscriptOffset();
  81
  82     /**
  83      * Return the font's subscript offset (the distance from the
  84      * baseline to where a subscript's baseline should be placed).
  85      * The value returned will be positive.
  86      */
  87     nscoord SubscriptOffset();
  88
  89     /**
  90      * Return the font's strikeout offset (the distance from the
  91      * baseline to where a strikeout should be placed) and size.
  92      * Positive values are above the baseline, negative below.
  93      */
  94     void GetStrikeout(nscoord& aOffset, nscoord& aSize);
  95
  96     /**
  97      * Return the font's underline offset (the distance from the
  98      * baseline to where a underline should be placed) and size.
  99      * Positive values are above the baseline, negative below.
 100      */
 101     void GetUnderline(nscoord& aOffset, nscoord& aSize);
 102
 103     /**
 104      * Returns the amount of internal leading for the font.
 105      * This is normally the difference between the max ascent
 106      * and the em ascent.
 107      */
 108     nscoord InternalLeading();
 109
 110     /**
 111      * Returns the amount of external leading for the font.
 112      * em ascent(?) plus external leading is the font designer's
 113      * recommended line-height for this font.
 114      */
 115     nscoord ExternalLeading();
 116
 117     /**
 118      * Returns the height of the em square.
 119      * This is em ascent plus em descent.
 120      */
 121     nscoord EmHeight();
 122
 123     /**
 124      * Returns the ascent part of the em square.
 125      */
 126     nscoord EmAscent();
 127
 128     /**
 129      * Returns the descent part of the em square.
 130      */
 131     nscoord EmDescent();
 132
 133     /**
 134      * Returns the height of the bounding box.
 135      * This is max ascent plus max descent.
 136      */
 137     nscoord MaxHeight();
 138
 139     /**
 140      * Returns the maximum distance characters in this font extend
 141      * above the base line.
 142      */
 143     nscoord MaxAscent();
 144
 145     /**
 146      * Returns the maximum distance characters in this font extend
 147      * below the base line.
 148      */
 149     nscoord MaxDescent();
 150
 151     /**
 152      * Returns the maximum character advance for the font.
 153      */
 154     nscoord MaxAdvance();
 155
 156     /**
 157      * Returns the average character width
 158      */
 159     nscoord AveCharWidth();
 160
 161     /**
 162      * Returns the often needed width of the space character
 163      */
 164     nscoord SpaceWidth();
 165
 166     /**
 167      * Returns the font associated with these metrics. The return value
 168      * is only defined after Init() has been called.
 169      */
 170     const nsFont &Font() { return mFont; }
 171
 172     /**
 173      * Returns the language associated with these metrics
 174      */
 175     nsIAtom* Language() { return mLanguage; }
 176
 177     int32_t GetMaxStringLength();
 178
 179     // Get the width for this string.  aWidth will be updated with the
 180     // width in points, not twips.  Callers must convert it if they
 181     // want it in another format.
 182     nscoord GetWidth(const char* aString, uint32_t aLength,
 183                      nsRenderingContext *aContext);
 184     nscoord GetWidth(const char16_t* aString, uint32_t aLength,
 185                      nsRenderingContext *aContext);
 186
 187     // Draw a string using this font handle on the surface passed in.
 188     void DrawString(const char *aString, uint32_t aLength,
 189                     nscoord aX, nscoord aY,
 190                     nsRenderingContext *aContext);
 191     void DrawString(const char16_t* aString, uint32_t aLength,
 192                     nscoord aX, nscoord aY,
 193                     nsRenderingContext *aContext,
 194                     nsRenderingContext *aTextRunConstructionContext);
 195
 196     nsBoundingMetrics GetBoundingMetrics(const char16_t *aString,
 197                                          uint32_t aLength,
 198                                          nsRenderingContext *aContext);
 199
 200     // Returns the LOOSE_INK_EXTENTS bounds of the text for determing the
 201     // overflow area of the string.
 202     nsBoundingMetrics GetInkBoundsForVisualOverflow(const char16_t *aString,
 203                                                     uint32_t aLength,
 204                                                     nsRenderingContext *aContext);
 205
 206     void SetTextRunRTL(bool aIsRTL) { mTextRunRTL = aIsRTL; }
 207     bool GetTextRunRTL() { return mTextRunRTL; }
 208
 209     gfxFontGroup* GetThebesFontGroup() { return mFontGroup; }
 210     gfxUserFontSet* GetUserFontSet() { return mFontGroup->GetUserFontSet(); }
 211
 212     int32_t AppUnitsPerDevPixel() { return mP2A; }
 213
 214 private:
 215     // Private destructor, to discourage deletion outside of Release():
 216     ~nsFontMetrics();
 217
 218     const gfxFont::Metrics& GetMetrics() const;
 219
 220     nsFont mFont;
 221     nsRefPtr<gfxFontGroup> mFontGroup;
 222     nsCOMPtr<nsIAtom> mLanguage;
 223     nsDeviceContext *mDeviceContext;
 224     int32_t mP2A;
 225     bool mTextRunRTL;
 226 };
 227
 228 #endif /* NSFONTMETRICS__H__ */