gfx/public/nsIFontMetrics.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either of the GNU General Public License Version 2 or later (the "GPL"),
  26  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef nsIFontMetrics_h___
  39 #define nsIFontMetrics_h___
  40
  41 #include "nsISupports.h"
  42 #include "nsCoord.h"
  43 #include "nsFont.h"
  44
  45 class nsString;
  46 class nsIDeviceContext;
  47 class nsIAtom;
  48 class gfxUserFontSet;
  49
  50 // IID for the nsIFontMetrics interface
  51 #define NS_IFONT_METRICS_IID   \
  52 { 0xc74cb770, 0xa33e, 0x11d1, \
  53 { 0xa8, 0x24, 0x00, 0x40, 0x95, 0x9a, 0x28, 0xc9 } }
  54
  55 //----------------------------------------------------------------------
  56
  57 /**
  58  * A native font handle
  59  */
  60 typedef void* nsFontHandle;
  61
  62 /**
  63  * Font metrics interface
  64  *
  65  * This interface may be somewhat misnamed. A better name might be
  66  * nsIFontList. The style system uses the nsFont struct for various font
  67  * properties, one of which is font-family, which can contain a *list* of
  68  * font names. The nsFont struct is "realized" by asking the device context
  69  * to cough up an nsIFontMetrics object, which contains a list of real font
  70  * handles, one for each font mentioned in font-family (and for each fallback
  71  * when we fall off the end of that list).
  72  *
  73  * The style system needs to have access to certain metrics, such as the
  74  * em height (for the CSS "em" unit), and we use the first Western font's
  75  * metrics for that purpose. The platform-specific implementations are
  76  * expected to select non-Western fonts that "fit" reasonably well with the
  77  * Western font that is loaded at Init time.
  78  */
  79 class nsIFontMetrics : public nsISupports
  80 {
  81 public:
  82   NS_DECLARE_STATIC_IID_ACCESSOR(NS_IFONT_METRICS_IID)
  83
  84   /**
  85    * Initialize the font metrics. Call this after creating the font metrics.
  86    * Font metrics you get from the font cache do NOT need to be initialized
  87    *
  88    * @see nsIDeviceContext#GetMetricsFor()
  89    */
  90   NS_IMETHOD  Init(const nsFont& aFont, nsIAtom* aLangGroup,
  91                    nsIDeviceContext *aContext, gfxUserFontSet *aUserFontSet = nsnull) = 0;
  92
  93   /**
  94    * Destroy this font metrics. This breaks the association between
  95    * the font metrics and the device context.
  96    */
  97   NS_IMETHOD  Destroy() = 0;
  98
  99   /**
 100    * Return the font's xheight property, scaled into app-units.
 101    */
 102   NS_IMETHOD  GetXHeight(nscoord& aResult) = 0;
 103
 104   /**
 105    * Return the font's superscript offset (the distance from the
 106    * baseline to where a superscript's baseline should be placed). The
 107    * value returned will be a positive value.
 108    */
 109   NS_IMETHOD  GetSuperscriptOffset(nscoord& aResult) = 0;
 110
 111   /**
 112    * Return the font's subscript offset (the distance from the
 113    * baseline to where a subscript's baseline should be placed). The
 114    * value returned will be a positive value.
 115    */
 116   NS_IMETHOD  GetSubscriptOffset(nscoord& aResult) = 0;
 117
 118   /**
 119    * Return the font's strikeout offset (the distance from the
 120    * baseline to where a strikeout should be placed) and size
 121    * Positive values are above the baseline, negative below.
 122    */
 123   NS_IMETHOD  GetStrikeout(nscoord& aOffset, nscoord& aSize) = 0;
 124
 125   /**
 126    * Return the font's underline offset (the distance from the
 127    * baseline to where a underline should be placed) and size.
 128    * Positive values are above the baseline, negative below.
 129    */
 130   NS_IMETHOD  GetUnderline(nscoord& aOffset, nscoord& aSize) = 0;
 131
 132   /**
 133    * Returns the height (in app units) of the font. This is ascent plus descent
 134    * plus any internal leading
 135    *
 136    * This method will be removed once the callers have been moved over to the
 137    * new GetEmHeight (and possibly GetMaxHeight).
 138    */
 139   NS_IMETHOD  GetHeight(nscoord &aHeight) = 0;
 140
 141   /**
 142    * Returns the amount of internal leading (in app units) for the font. This
 143    * is computed as the "height  - (ascent + descent)"
 144    */
 145   NS_IMETHOD  GetInternalLeading(nscoord &aLeading) = 0;
 146
 147   /**
 148    * Returns the amount of external leading (in app units) as suggested by font
 149    * vendor. This value is suggested by font vendor to add to normal line-height
 150    * beside font height.
 151    */
 152   NS_IMETHOD  GetExternalLeading(nscoord &aLeading) = 0;
 153
 154   /**
 155    * Returns the height (in app units) of the Western font's em square. This is
 156    * em ascent plus em descent.
 157    */
 158   NS_IMETHOD  GetEmHeight(nscoord &aHeight) = 0;
 159
 160   /**
 161    * Returns, in app units, the ascent part of the Western font's em square.
 162    */
 163   NS_IMETHOD  GetEmAscent(nscoord &aAscent) = 0;
 164
 165   /**
 166    * Returns, in app units, the descent part of the Western font's em square.
 167    */
 168   NS_IMETHOD  GetEmDescent(nscoord &aDescent) = 0;
 169
 170   /**
 171    * Returns the height (in app units) of the Western font's bounding box.
 172    * This is max ascent plus max descent.
 173    */
 174   NS_IMETHOD  GetMaxHeight(nscoord &aHeight) = 0;
 175
 176   /**
 177    * Returns, in app units, the maximum distance characters in this font extend
 178    * above the base line.
 179    */
 180   NS_IMETHOD  GetMaxAscent(nscoord &aAscent) = 0;
 181
 182   /**
 183    * Returns, in app units, the maximum distance characters in this font extend
 184    * below the base line.
 185    */
 186   NS_IMETHOD  GetMaxDescent(nscoord &aDescent) = 0;
 187
 188   /**
 189    * Returns, in app units, the maximum character advance for the font
 190    */
 191   NS_IMETHOD  GetMaxAdvance(nscoord &aAdvance) = 0;
 192
 193   /**
 194    * Returns the font associated with these metrics. The return value
 195    * is only defined after Init() has been called.
 196    */
 197   const nsFont &Font() { return mFont; }
 198
 199   /**
 200    * Returns the language group associated with these metrics
 201    */
 202   NS_IMETHOD  GetLangGroup(nsIAtom** aLangGroup) = 0;
 203
 204   /**
 205    * Returns the font handle associated with these metrics
 206    */
 207   NS_IMETHOD  GetFontHandle(nsFontHandle &aHandle) = 0;
 208
 209   /**
 210    * Returns the average character width
 211    */
 212   NS_IMETHOD  GetAveCharWidth(nscoord& aAveCharWidth) = 0;
 213
 214   /**
 215    * Returns the often needed width of the space character
 216    */
 217   NS_IMETHOD  GetSpaceWidth(nscoord& aSpaceCharWidth) = 0;
 218
 219 protected:
 220
 221   nsFont mFont;         // The font for this metrics object.
 222 };
 223
 224 NS_DEFINE_STATIC_IID_ACCESSOR(nsIFontMetrics, NS_IFONT_METRICS_IID)
 225
 226 #endif /* nsIFontMetrics_h___ */