gfx/public/nsIRenderingContext.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  *   Roland Mainz <roland.mainz@informatik.med.uni-giessen.de>
  24  *   Leon Sha <leon.sha@sun.com>
  25  *   Boris Zbarsky <bzbarsky@mit.edu>
  26  *
  27  * Alternatively, the contents of this file may be used under the terms of
  28  * either of the GNU General Public License Version 2 or later (the "GPL"),
  29  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30  * in which case the provisions of the GPL or the LGPL are applicable instead
  31  * of those above. If you wish to allow use of your version of this file only
  32  * under the terms of either the GPL or the LGPL, and not to allow others to
  33  * use your version of this file under the terms of the MPL, indicate your
  34  * decision by deleting the provisions above and replace them with the notice
  35  * and other provisions required by the GPL or the LGPL. If you do not delete
  36  * the provisions above, a recipient may use your version of this file under
  37  * the terms of any one of the MPL, the GPL or the LGPL.
  38  *
  39  * ***** END LICENSE BLOCK ***** */
  40
  41 #ifndef nsIRenderingContext_h___
  42 #define nsIRenderingContext_h___
  43
  44 #include "nscore.h"
  45 #include "nsISupports.h"
  46 #include "nsColor.h"
  47 #include "nsCoord.h"
  48 #include "nsRect.h"
  49 #include "nsPoint.h"
  50 #include "nsSize.h"
  51 #include <stdio.h>
  52
  53 class nsIWidget;
  54 class nsIFontMetrics;
  55 class nsTransform2D;
  56 class nsString;
  57 class nsIDeviceContext;
  58 class nsIRegion;
  59 class nsIAtom;
  60
  61 struct nsFont;
  62 struct nsTextDimensions;
  63 #ifdef MOZ_MATHML
  64 struct nsBoundingMetrics;
  65 #endif
  66
  67 class gfxASurface;
  68 class gfxContext;
  69
  70 /* gfx2 */
  71 class imgIContainer;
  72
  73 //cliprect/region combination methods
  74
  75 typedef enum
  76 {
  77   nsClipCombine_kIntersect = 0,
  78   nsClipCombine_kUnion = 1,
  79   nsClipCombine_kSubtract = 2,
  80   nsClipCombine_kReplace = 3
  81 } nsClipCombine;
  82
  83 //linestyles
  84 typedef enum
  85 {
  86   nsLineStyle_kNone   = 0,
  87   nsLineStyle_kSolid  = 1,
  88   nsLineStyle_kDashed = 2,
  89   nsLineStyle_kDotted = 3
  90 } nsLineStyle;
  91
  92 typedef enum
  93 {
  94   nsPenMode_kNone   = 0,
  95   nsPenMode_kInvert = 1
  96 } nsPenMode;
  97
  98
  99 // IID for the nsIRenderingContext interface
 100 // a67de6b9-fffa-465c-abea-d7b394588a07
 101 #define NS_IRENDERING_CONTEXT_IID \
 102  { 0xa67de6b9, 0xfffa, 0x465c,{0xab, 0xea, 0xd7, 0xb3, 0x94, 0x58, 0x8a, 0x07}}
 103
 104 //----------------------------------------------------------------------
 105
 106 // RenderingContext interface
 107 class nsIRenderingContext : public nsISupports
 108 {
 109 public:
 110   NS_DECLARE_STATIC_IID_ACCESSOR(NS_IRENDERING_CONTEXT_IID)
 111
 112   //TBD: bind/unbind, transformation of scalars (hacky),
 113   //potential drawmode for selection, polygons. MMP
 114
 115   /**
 116    * Initialize the RenderingContext
 117    * @param aContext the device context to use.
 118    * @param aWidget the widget to hook up to
 119    * @result The result of the initialization, NS_Ok if no errors
 120    */
 121   NS_IMETHOD Init(nsIDeviceContext* aContext, nsIWidget *aWidget) = 0;
 122
 123   /**
 124    * Initialize the RenderingContext
 125    * @param aContext the device context to use for the drawing.
 126    * @param aThebesSurface the Thebes gfxASurface to which to draw
 127    * @result The result of the initialization, NS_Ok if no errors
 128    */
 129   NS_IMETHOD Init(nsIDeviceContext* aContext, gfxASurface* aThebesSurface) = 0;
 130
 131   /**
 132    * Initialize the RenderingContext
 133    * @param aContext the device context to use for the drawing.
 134    * @param aThebesContext an existing thebes context to use for the drawing
 135    * @result The result of the initialization, NS_Ok if no errors
 136    */
 137   NS_IMETHOD Init(nsIDeviceContext* aContext, gfxContext* aThebesContext) = 0;
 138
 139   /**
 140    * Get the DeviceContext that this RenderingContext was initialized
 141    * with.  This function addrefs the device context.  Though it might
 142    * be better if it just returned it directly, without addrefing.
 143    * @result the device context
 144    */
 145   NS_IMETHOD GetDeviceContext(nsIDeviceContext *& aDeviceContext) = 0;
 146
 147   /**
 148    * Save a graphical state onto a stack.
 149    */
 150   NS_IMETHOD PushState(void) = 0;
 151
 152   /**
 153    * Get and and set RenderingContext to this graphical state
 154    */
 155   NS_IMETHOD PopState(void) = 0;
 156
 157   // XXX temporary
 158   NS_IMETHOD PushFilter(const nsRect& aRect, PRBool aAreaIsOpaque, float aOpacity)
 159   { return NS_ERROR_NOT_IMPLEMENTED; }
 160   NS_IMETHOD PopFilter()
 161   { return NS_ERROR_NOT_IMPLEMENTED; }
 162
 163   /**
 164    * Sets the clipping for the RenderingContext to the passed in rectangle.
 165    * The rectangle is in app units!
 166    * @param aRect The rectangle to set the clipping rectangle to
 167    * @param aCombine how to combine this rect with the current clip region.
 168    *        see the bottom of nsIRenderingContext.h
 169    */
 170   NS_IMETHOD SetClipRect(const nsRect& aRect, nsClipCombine aCombine) = 0;
 171
 172   /**
 173    * Sets the line style for the RenderingContext
 174    * @param aLineStyle The line style
 175    * @return NS_OK if the line style is correctly set
 176    */
 177   NS_IMETHOD SetLineStyle(nsLineStyle aLineStyle) = 0;
 178
 179   /**
 180    * Sets the clipping for the RenderingContext to the passed in region.
 181    * The region is in device coordinates!
 182    * @param aRegion The region to set the clipping area to, IN DEVICE COORDINATES
 183    * @param aCombine how to combine this region with the current clip region.
 184    *        see the bottom of nsIRenderingContext.h
 185    */
 186   NS_IMETHOD SetClipRegion(const nsIRegion& aRegion, nsClipCombine aCombine) = 0;
 187
 188   /**
 189    * Sets the forground color for the RenderingContext
 190    * @param aColor The color to set the RenderingContext to
 191    */
 192   NS_IMETHOD SetColor(nscolor aColor) = 0;
 193
 194   /**
 195    * Get the forground color for the RenderingContext
 196    * @return The current forground color of the RenderingContext
 197    */
 198   NS_IMETHOD GetColor(nscolor &aColor) const = 0;
 199
 200   /**
 201    * Sets the font for the RenderingContext
 202    * @param aFont The font to use in the RenderingContext
 203    */
 204   NS_IMETHOD SetFont(const nsFont& aFont, nsIAtom* aLangGroup) = 0;
 205
 206   /**
 207    * Sets the font for the RenderingContext
 208    * @param aFontMetric The font metrics representing the
 209    *        font to use in the RenderingContext
 210    */
 211   NS_IMETHOD SetFont(nsIFontMetrics *aFontMetrics) = 0;
 212
 213   /**
 214    * Get the current fontmetrics for the RenderingContext
 215    * @return The current font of the RenderingContext
 216    */
 217   NS_IMETHOD GetFontMetrics(nsIFontMetrics *&aFontMetrics) = 0;
 218
 219   /**
 220    *  Add in a translate to the RenderingContext's transformation matrix
 221    * @param aX The horizontal translation
 222    * @param aY The vertical translation
 223    */
 224   NS_IMETHOD Translate(nscoord aX, nscoord aY) = 0;
 225
 226   /**
 227    * Set the translation compoennt of the current transformation matrix.
 228    * Useful to set it to a known pixel value without incurring roundoff
 229    * errors.
 230    */
 231   NS_IMETHOD SetTranslation(nscoord aX, nscoord aY) = 0;
 232
 233   /**
 234    *  Add in a scale to the RenderingContext's transformation matrix
 235    * @param aX The horizontal scale
 236    * @param aY The vertical scale
 237    */
 238   NS_IMETHOD Scale(float aSx, float aSy) = 0;
 239
 240   struct PushedTranslation {
 241     float mSavedX, mSavedY;
 242   };
 243
 244   class AutoPushTranslation {
 245     nsIRenderingContext* mCtx;
 246     PushedTranslation mPushed;
 247   public:
 248     AutoPushTranslation(nsIRenderingContext* aCtx, nscoord aX, nscoord aY)
 249       : mCtx(aCtx) {
 250       mCtx->PushTranslation(&mPushed);
 251       mCtx->Translate(aX, aY);
 252     }
 253     ~AutoPushTranslation() {
 254       mCtx->PopTranslation(&mPushed);
 255     }
 256   };
 257
 258   NS_IMETHOD PushTranslation(PushedTranslation* aState) = 0;
 259
 260   NS_IMETHOD PopTranslation(PushedTranslation* aState) = 0;
 261
 262   /**
 263    * Get the current transformation matrix for the RenderingContext
 264    * @return The transformation matrix for the RenderingContext
 265    */
 266   NS_IMETHOD GetCurrentTransform(nsTransform2D *&aTransform) = 0;
 267
 268   /**
 269    * Draw a line
 270    * @param aXO starting horiztonal coord in twips
 271    * @param aY0 starting vertical coord in twips
 272    * @param aX1 end horiztonal coord in twips
 273    * @param aY1 end vertical coord in twips
 274    */
 275   NS_IMETHOD DrawLine(nscoord aX0, nscoord aY0, nscoord aX1, nscoord aY1) = 0;
 276
 277   /**
 278    * Draw a rectangle
 279    * @param aRect The rectangle to draw
 280    */
 281   NS_IMETHOD DrawRect(const nsRect& aRect) = 0;
 282
 283   /**
 284    * Draw a rectangle
 285    * @param aX Horizontal left Coordinate in twips
 286    * @param aY Vertical top Coordinate in twips
 287    * @param aWidth Width of rectangle in twips
 288    * @param aHeight Height of rectangle in twips
 289    */
 290   NS_IMETHOD DrawRect(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight) = 0;
 291
 292   /**
 293    * Fill a rectangle in the current foreground color
 294    * @param aRect The rectangle to draw
 295    */
 296   NS_IMETHOD FillRect(const nsRect& aRect) = 0;
 297
 298   /**
 299    * Fill a rectangle in the current foreground color
 300    * @param aX Horizontal left Coordinate in twips
 301    * @param aY Vertical top Coordinate in twips
 302    * @param aWidth Width of rectangle in twips
 303    * @param aHeight Height of rectangle in twips
 304    */
 305   NS_IMETHOD FillRect(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight) = 0;
 306
 307   /**
 308    * XOR Invert a rectangle in the current foreground color
 309    * @param aRect The rectangle to draw
 310    */
 311   NS_IMETHOD InvertRect(const nsRect& aRect) = 0;
 312
 313   /**
 314    * XOR Invert a rectangle in the current foreground color
 315    * @param aX Horizontal left Coordinate in twips
 316    * @param aY Vertical top Coordinate in twips
 317    * @param aWidth Width of rectangle in twips
 318    * @param aHeight Height of rectangle in twips
 319    */
 320   NS_IMETHOD InvertRect(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight) = 0;
 321
 322   /**
 323    * Fill a poly in the current foreground color
 324    * @param aPoints points to use for the drawing, last must equal first
 325    * @param aNumPonts number of points in the polygon
 326    */
 327   NS_IMETHOD FillPolygon(const nsPoint aPoints[], PRInt32 aNumPoints) = 0;
 328
 329   /**
 330    * Draw an ellipse in the current foreground color
 331    * @param aRect The rectangle define bounds of ellipse to draw
 332    */
 333   NS_IMETHOD DrawEllipse(const nsRect& aRect) = 0;
 334
 335   /**
 336    * Draw an ellipse in the current foreground color
 337    * @param aX Horizontal left Coordinate in twips
 338    * @param aY Vertical top Coordinate in twips
 339    * @param aWidth Width of horizontal axis in twips
 340    * @param aHeight Height of vertical axis in twips
 341    */
 342   NS_IMETHOD DrawEllipse(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight) = 0;
 343
 344   /**
 345    * Fill an ellipse in the current foreground color
 346    * @param aRect The rectangle define bounds of ellipse to draw
 347    */
 348   NS_IMETHOD FillEllipse(const nsRect& aRect) = 0;
 349
 350   /**
 351    * Fill an ellipse in the current foreground color
 352    * @param aX Horizontal left Coordinate in twips
 353    * @param aY Vertical top Coordinate in twips
 354    * @param aWidth Width of horizontal axis in twips
 355    * @param aHeight Height of vertical axis in twips
 356    */
 357   NS_IMETHOD FillEllipse(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight) = 0;
 358
 359   /**
 360    * Returns the width (in app units) of an 8-bit character
 361    * If no font has been Set, the results are undefined.
 362    * @param aC character to measure
 363    * @param aWidth out parameter for width
 364    * @return error status
 365    */
 366   NS_IMETHOD GetWidth(char aC, nscoord &aWidth) = 0;
 367
 368   /**
 369    * Returns the width (in app units) of a unicode character
 370    * If no font has been Set, the results are undefined.
 371    * @param aC character to measure
 372    * @param aWidth out parameter for width
 373    * @param aFontID an optional out parameter used to store a
 374    *        font identifier that can be passed into the DrawString()
 375    *        methods to speed rendering
 376    * @return error status
 377    */
 378   NS_IMETHOD GetWidth(PRUnichar aC, nscoord &aWidth,
 379                       PRInt32 *aFontID = nsnull) = 0;
 380
 381   /**
 382    * Returns the width (in app units) of an nsString
 383    * If no font has been Set, the results are undefined.
 384    * @param aString string to measure
 385    * @param aWidth out parameter for width
 386    * @param aFontID an optional out parameter used to store a
 387    *        font identifier that can be passed into the DrawString()
 388    *        methods to speed rendering
 389    * @return error status
 390    */
 391   NS_IMETHOD GetWidth(const nsString& aString, nscoord &aWidth,
 392                       PRInt32 *aFontID = nsnull) = 0;
 393
 394   /**
 395    * Returns the width (in app units) of an 8-bit character string
 396    * If no font has been Set, the results are undefined.
 397    * @param aString string to measure
 398    * @param aWidth out parameter for width
 399    * @return error status
 400    */
 401   NS_IMETHOD GetWidth(const char* aString, nscoord& aWidth) = 0;
 402
 403   /**
 404    * Returns the width (in app units) of an 8-bit character string
 405    * If no font has been Set, the results are undefined.
 406    * @param aString string to measure
 407    * @param aLength number of characters in string
 408    * @param aWidth out parameter for width
 409    * @return error status
 410    */
 411   NS_IMETHOD GetWidth(const char* aString, PRUint32 aLength,
 412                       nscoord& aWidth) = 0;
 413
 414   /**
 415    * Returns the width (in app units) of a Unicode character string
 416    * If no font has been Set, the results are undefined.
 417    * @param aString string to measure
 418    * @param aLength number of characters in string
 419    * @param aWidth out parameter for width
 420    * @param aFontID an optional out parameter used to store a
 421    *        font identifier that can be passed into the DrawString()
 422    *        methods to speed rendering
 423    * @return error status
 424    */
 425   NS_IMETHOD GetWidth(const PRUnichar *aString, PRUint32 aLength,
 426                       nscoord &aWidth, PRInt32 *aFontID = nsnull) = 0;
 427
 428   /**
 429    * Returns the dimensions of a string, i.e., the overall extent of a string
 430    * whose rendering may involve switching between different fonts that have
 431    * different metrics.
 432    * @param aString string to measure
 433    * @param aLength number of characters in string
 434    * @param aFontID an optional out parameter used to store a
 435    *        font identifier that can be passed into the DrawString()
 436    *        methods to speed measurements
 437    * @return aDimensions struct that contains the extent of the string (see below)
 438    */
 439   NS_IMETHOD GetTextDimensions(const char* aString, PRUint32 aLength,
 440                                nsTextDimensions& aDimensions) = 0;
 441   NS_IMETHOD GetTextDimensions(const PRUnichar* aString, PRUint32 aLength,
 442                                nsTextDimensions& aDimensions, PRInt32* aFontID = nsnull) = 0;
 443
 444 #if defined(_WIN32) || defined(XP_OS2) || defined(MOZ_X11) || defined(XP_BEOS)
 445   /**
 446    * Given an available width and an array of break points,
 447    * returns the dimensions (in app units) of the text that fit and
 448    * the number of characters that fit. The number of characters
 449    * corresponds to an entry in the break array.
 450    * If no font has been set, the results are undefined.
 451    * @param aString, string to measure
 452    * @param aLength, number of characters in string
 453    * @param aAvailWidth, the available space in which the text must fit
 454    * @param aBreaks, array of places to break. Specified as offsets from the
 455    *          start of the string
 456    * @param aNumBreaks, the number of entries in the break array. The last
 457    *          entry in the break array must equal the length of the string
 458    * @param aDimensions, out parameter for the dimensions, the ascent and descent
 459    *           of the last word are left out to allow possible line-breaking before
 460    *           the last word. However, the width of the last word is included.
 461    * @param aNumCharsFit, the number of characters that fit in the available space
 462    * @param aLastWordDimensions, dimensions of the last word, the width field,
 463    *             dimensions.width, should be -1 for an unknown width. But the
 464    *             ascent and descent are expected to be known.
 465    * @param aFontID, an optional out parameter used to store a
 466    *        font identifier that can be passed into the DrawString()
 467    *        methods to speed rendering
 468    * @return error status
 469    */
 470   NS_IMETHOD GetTextDimensions(const char*       aString,
 471                                PRInt32           aLength,
 472                                PRInt32           aAvailWidth,
 473                                PRInt32*          aBreaks,
 474                                PRInt32           aNumBreaks,
 475                                nsTextDimensions& aDimensions,
 476                                PRInt32&          aNumCharsFit,
 477                                nsTextDimensions& aLastWordDimensions,
 478                                PRInt32*          aFontID = nsnull) = 0;
 479
 480   NS_IMETHOD GetTextDimensions(const PRUnichar*  aString,
 481                                PRInt32           aLength,
 482                                PRInt32           aAvailWidth,
 483                                PRInt32*          aBreaks,
 484                                PRInt32           aNumBreaks,
 485                                nsTextDimensions& aDimensions,
 486                                PRInt32&          aNumCharsFit,
 487                                nsTextDimensions& aLastWordDimensions,
 488                                PRInt32*          aFontID = nsnull) = 0;
 489 #endif
 490
 491   /**
 492    * Draw a string in the RenderingContext
 493    * @param aString The string to draw
 494    * @param aLength The length of the aString
 495    * @param aX Horizontal starting point of baseline
 496    * @param aY Vertical starting point of baseline.
 497    * @param aSpacing inter-character spacing to apply
 498    */
 499   NS_IMETHOD DrawString(const char *aString, PRUint32 aLength,
 500                         nscoord aX, nscoord aY,
 501                         const nscoord* aSpacing = nsnull) = 0;
 502
 503   /**
 504    * Draw a string in the RenderingContext
 505    * @param aString A PRUnichar of the string
 506    * @param aLength The length of the aString
 507    * @param aX Horizontal starting point of baseline
 508    * @param aY Vertical starting point of baseline.
 509    * @param aFontID an optional parameter used to speed font
 510    *        selection for complex unicode strings. the value
 511    *        passed is returned by the DrawString() methods.
 512    * @param aSpacing inter-character spacing to apply
 513    */
 514   NS_IMETHOD DrawString(const PRUnichar *aString, PRUint32 aLength,
 515                         nscoord aX, nscoord aY,
 516                         PRInt32 aFontID = -1,
 517                         const nscoord* aSpacing = nsnull) = 0;
 518
 519   /**
 520    * Draw a string in the RenderingContext
 521    * @param aString A nsString of the string
 522    * @param aX Horizontal starting point of baseline
 523    * @param aY Vertical starting point of baseline.
 524    * @param aFontID an optional parameter used to speed font
 525    *        selection for complex unicode strings. the value
 526    *        passed is returned by the DrawString() methods.
 527    * @param aSpacing inter-character spacing to apply
 528    */
 529   NS_IMETHOD DrawString(const nsString& aString, nscoord aX, nscoord aY,
 530                         PRInt32 aFontID = -1,
 531                         const nscoord* aSpacing = nsnull) = 0;
 532
 533   enum GraphicDataType {
 534     NATIVE_CAIRO_CONTEXT = 1,
 535     NATIVE_GDK_DRAWABLE = 2,
 536     NATIVE_WINDOWS_DC = 3,
 537     NATIVE_MAC_THING = 4,
 538     NATIVE_THEBES_CONTEXT = 5,
 539     NATIVE_OS2_PS = 6
 540   };
 541   /**
 542    * Retrieve the native graphic data given by aType. Return
 543    * nsnull if not available.
 544    */
 545   virtual void* GetNativeGraphicData(GraphicDataType aType) = 0;
 546
 547 #ifdef MOZ_MATHML
 548   /**
 549    * Returns bounding metrics (in app units) of an 8-bit character string
 550    * @param aString string to measure
 551    * @param aLength number of characters in string
 552    * @return aBoundingMetrics struct that contains various metrics (see below)
 553    * @return error status
 554    */
 555   NS_IMETHOD
 556   GetBoundingMetrics(const char*        aString,
 557                      PRUint32           aLength,
 558                      nsBoundingMetrics& aBoundingMetrics) = 0;
 559   /**
 560    * Returns bounding metrics (in app units) of an Unicode character string
 561    * @param aString string to measure
 562    * @param aLength number of characters in string
 563    * @param aFontID an optional out parameter used to store a
 564    *        font identifier that can be passed into the GetBoundingMetrics()
 565    *        methods to speed measurements
 566    * @return aBoundingMetrics struct that contains various metrics (see below)
 567    * @return error status
 568    */
 569   NS_IMETHOD
 570   GetBoundingMetrics(const PRUnichar*   aString,
 571                      PRUint32           aLength,
 572                      nsBoundingMetrics& aBoundingMetrics,
 573                      PRInt32*           aFontID = nsnull) = 0;
 574 #endif
 575
 576
 577   /**
 578    * Let the device context know whether we want text reordered with
 579    * right-to-left base direction
 580    */
 581   NS_IMETHOD SetRightToLeftText(PRBool aIsRTL) = 0;
 582
 583   /**
 584    * This sets the direction of the text; all characters should be
 585    * overridden to have this direction.
 586    */
 587   virtual void SetTextRunRTL(PRBool aIsRTL) = 0;
 588
 589   /*
 590    * Tiles an image over an area
 591    * @param aImage       Image to tile
 592    * @param aXImageStart x location where the origin (0,0) of the image starts
 593    * @param aYImageStart y location where the origin (0,0) of the image starts
 594    * @param aTargetRect  area to draw to
 595    * @param aSubimageRect the subimage (in tile space) which we expect to
 596    * sample from; may be null to indicate that the whole image is
 597    * OK to sample from
 598    */
 599   NS_IMETHOD DrawTile(imgIContainer *aImage,
 600                       nscoord aXImageStart, nscoord aYImageStart,
 601                       const nsRect * aTargetRect,
 602                       const nsIntRect * aSubimageRect) = 0;
 603
 604   /**
 605    * Find the closest cursor position for a given x coordinate.
 606    *
 607    * This will find the closest byte index for a given x coordinate.
 608    * This takes into account grapheme clusters and bidi text.
 609    *
 610    * @param aText Text on which to operate.
 611    * @param aLength Length of the text.
 612    * @param aPt the x/y position in the string to check.
 613    *
 614    * @return Index where the cursor falls.  If the return is zero,
 615    *   it's before the first character, if it falls off the end of
 616    *   the string it's the length of the string + 1.
 617    *
 618    */
 619   virtual PRInt32 GetPosition(const PRUnichar *aText,
 620                               PRUint32 aLength,
 621                               nsPoint aPt) = 0;
 622
 623   /**
 624    * Get the width for the specific range of a given string.
 625    *
 626    * This function is similar to other GetWidth functions, except that
 627    * it gets the width for a part of the string instead of the entire
 628    * string.  This is useful when you're interested in finding out the
 629    * length of a chunk in the middle of the string.  Lots of languages
 630    * require you to include surrounding information to accurately
 631    * determine the length of a substring.
 632    *
 633    * @param aText Text on which to operate
 634    * @param aLength Length of the text
 635    * @param aStart Start index into the string
 636    * @param aEnd End index into the string (inclusive)
 637    * @param aWidth Returned with in app coordinates
 638    *
 639    */
 640   NS_IMETHOD GetRangeWidth(const PRUnichar *aText,
 641                            PRUint32 aLength,
 642                            PRUint32 aStart,
 643                            PRUint32 aEnd,
 644                            PRUint32 &aWidth) = 0;
 645
 646   /**
 647    * Get the width for the specific range of a given string.
 648    *
 649    * Same as GetRangeWidth for PRUnichar, but takes a char * as the
 650    * text argument.
 651    *
 652    */
 653   NS_IMETHOD GetRangeWidth(const char *aText,
 654                            PRUint32 aLength,
 655                            PRUint32 aStart,
 656                            PRUint32 aEnd,
 657                            PRUint32 &aWidth) = 0;
 658
 659   /**
 660    * Render an encapsulated postscript object onto the current rendering
 661    * surface.
 662    *
 663    * The EPS object must conform to the EPSF standard. See Adobe
 664    * specification #5002, "Encapsulated PostScript File Format Specification"
 665    * at <http://partners.adobe.com/asn/developer/pdfs/tn/5002.EPSF_Spec.pdf>.
 666    * In particular, the EPS object must contain a BoundingBox comment.
 667    *
 668    * @param aRect  Rectangle in which to render the EPSF.
 669    * @param aDataFile - plugin data stored in a file
 670    * @return NS_OK for success, or a suitable error value.
 671    *         NS_ERROR_NOT_IMPLEMENTED is returned if the rendering context
 672    *         doesn't support rendering EPSF,
 673    */
 674   NS_IMETHOD RenderEPS(const nsRect& aRect, FILE *aDataFile) = 0;
 675
 676   /**
 677    * Return the Thebes gfxContext associated with this nsIRenderingContext.
 678    */
 679   virtual gfxContext *ThebesContext() = 0;
 680 };
 681
 682 NS_DEFINE_STATIC_IID_ACCESSOR(nsIRenderingContext, NS_IRENDERING_CONTEXT_IID)
 683
 684 //flags for copy CopyOffScreenBits
 685
 686 //when performing the blit, use the region, if any,
 687 //that exists in the source drawingsurface as a
 688 //blit mask.
 689 #define NS_COPYBITS_USE_SOURCE_CLIP_REGION  0x0001
 690
 691 //transform the source offsets by the xform in the
 692 //rendering context
 693 #define NS_COPYBITS_XFORM_SOURCE_VALUES     0x0002
 694
 695 //transform the destination rect by the xform in the
 696 //rendering context
 697 #define NS_COPYBITS_XFORM_DEST_VALUES       0x0004
 698
 699 //this is basically a hack and is used by callers
 700 //who have selected an alternate drawing surface and
 701 //wish the copy to happen to that buffer rather than
 702 //the "front" buffer. i'm not proud of this. MMP
 703 //XXX: This is no longer needed by the XPCODE. It will
 704 //be removed once all of the platform specific nsRenderingContext's
 705 //stop using it.
 706 #define NS_COPYBITS_TO_BACK_BUFFER          0x0008
 707
 708 /* Struct used to represent the overall extent of a string
 709    whose rendering may involve switching between different
 710    fonts that have different metrics.
 711 */
 712 struct nsTextDimensions {
 713   // max ascent amongst all the fonts needed to represent the string
 714   nscoord ascent;
 715
 716   // max descent amongst all the fonts needed to represent the string
 717   nscoord descent;
 718
 719   // width of the string
 720   nscoord width;
 721
 722
 723   nsTextDimensions()
 724   {
 725     Clear();
 726   }
 727
 728   /* Set all member data to zero */
 729   void
 730   Clear() {
 731     ascent = descent = width = 0;
 732   }
 733
 734   /* Sum with another dimension */
 735   void
 736   Combine(const nsTextDimensions& aOther) {
 737     if (ascent < aOther.ascent) ascent = aOther.ascent;
 738     if (descent < aOther.descent) descent = aOther.descent;
 739     width += aOther.width;
 740   }
 741 };
 742
 743 #ifdef MOZ_MATHML
 744 /* Struct used for accurate measurements of a string in order
 745    to allow precise positioning when processing MathML.
 746 */
 747 struct nsBoundingMetrics {
 748
 749   ///////////
 750   // Metrics that _exactly_ enclose the text:
 751
 752   // The character coordinate system is the one used on X Windows:
 753   // 1. The origin is located at the intersection of the baseline
 754   //    with the left of the character's cell.
 755   // 2. All horizontal bearings are oriented from left to right.
 756   // 3. The ascent is oriented from bottom to top (being 0 at the orgin).
 757   // 4. The descent is oriented from top to bottom (being 0 at the origin).
 758
 759   // Note that Win32/Mac/PostScript use a different convention for
 760   // the descent (all vertical measurements are oriented from bottom
 761   // to top on these palatforms). Make sure to flip the sign of the
 762   // descent on these platforms for cross-platform compatibility.
 763
 764   // Any of the following member variables listed here can have
 765   // positive or negative value.
 766
 767   nscoord leftBearing;
 768        /* The horizontal distance from the origin of the drawing
 769           operation to the left-most part of the drawn string. */
 770
 771   nscoord rightBearing;
 772        /* The horizontal distance from the origin of the drawing
 773           operation to the right-most part of the drawn string.
 774           The _exact_ width of the string is therefore:
 775           rightBearing - leftBearing */
 776
 777   nscoord ascent;
 778        /* The vertical distance from the origin of the drawing
 779           operation to the top-most part of the drawn string. */
 780
 781   nscoord descent;
 782        /* The vertical distance from the origin of the drawing
 783           operation to the bottom-most part of the drawn string.
 784           The _exact_ height of the string is therefore:
 785           ascent + descent */
 786
 787   //////////
 788   // Metrics for placing other surrounding text:
 789
 790   nscoord width;
 791        /* The horizontal distance from the origin of the drawing
 792           operation to the correct origin for drawing another string
 793           to follow the current one. Depending on the font, this
 794           could be greater than or less than the right bearing. */
 795
 796   nsBoundingMetrics() {
 797     Clear();
 798   }
 799
 800   //////////
 801   // Utility methods and operators:
 802
 803   /* Set all member data to zero */
 804   void
 805   Clear() {
 806     leftBearing = rightBearing = 0;
 807     ascent = descent = width = 0;
 808   }
 809
 810   /* Append another bounding metrics */
 811   void
 812   operator += (const nsBoundingMetrics& bm) {
 813     if (ascent + descent == 0 && rightBearing - leftBearing == 0) {
 814       ascent = bm.ascent;
 815       descent = bm.descent;
 816       leftBearing = width + bm.leftBearing;
 817       rightBearing = width + bm.rightBearing;
 818     }
 819     else {
 820       if (ascent < bm.ascent) ascent = bm.ascent;
 821       if (descent < bm.descent) descent = bm.descent;
 822       leftBearing = PR_MIN(leftBearing, width + bm.leftBearing);
 823       rightBearing = PR_MAX(rightBearing, width + bm.rightBearing);
 824     }
 825     width += bm.width;
 826   }
 827 };
 828 #endif // MOZ_MATHML
 829
 830 #endif /* nsIRenderingContext_h___ */