Back to index

lightning-sunbird  0.9+nobinonly
nsIRenderingContext.h
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is mozilla.org code.
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *   Roland Mainz <roland.mainz@informatik.med.uni-giessen.de>
00024  *   Leon Sha <leon.sha@sun.com>
00025  *   Boris Zbarsky <bzbarsky@mit.edu>
00026  *
00027  * Alternatively, the contents of this file may be used under the terms of
00028  * either of the GNU General Public License Version 2 or later (the "GPL"),
00029  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00030  * in which case the provisions of the GPL or the LGPL are applicable instead
00031  * of those above. If you wish to allow use of your version of this file only
00032  * under the terms of either the GPL or the LGPL, and not to allow others to
00033  * use your version of this file under the terms of the MPL, indicate your
00034  * decision by deleting the provisions above and replace them with the notice
00035  * and other provisions required by the GPL or the LGPL. If you do not delete
00036  * the provisions above, a recipient may use your version of this file under
00037  * the terms of any one of the MPL, the GPL or the LGPL.
00038  *
00039  * ***** END LICENSE BLOCK ***** */
00040 
00041 #ifndef nsIRenderingContext_h___
00042 #define nsIRenderingContext_h___
00043 
00044 #include "nscore.h"
00045 #include "nsISupports.h"
00046 #include "nsColor.h"
00047 #include "nsCoord.h"
00048 #include "nsIDrawingSurface.h"
00049 #include <stdio.h>
00050 
00051 class nsIWidget;
00052 class nsIFontMetrics;
00053 class nsTransform2D;
00054 class nsString;
00055 class nsIDeviceContext;
00056 class nsIRegion;
00057 class nsIAtom;
00058 
00059 struct nsFont;
00060 struct nsPoint;
00061 struct nsRect;
00062 struct nsTextDimensions;
00063 #ifdef MOZ_MATHML
00064 struct nsBoundingMetrics;
00065 #endif
00066 
00067 /* gfx2 */
00068 class imgIContainer;
00069 
00070 //cliprect/region combination methods
00071 
00072 typedef enum
00073 {
00074   nsClipCombine_kIntersect = 0,
00075   nsClipCombine_kUnion = 1,
00076   nsClipCombine_kSubtract = 2,
00077   nsClipCombine_kReplace = 3
00078 } nsClipCombine;
00079 
00080 //linestyles
00081 typedef enum
00082 {
00083   nsLineStyle_kNone   = 0,
00084   nsLineStyle_kSolid  = 1,
00085   nsLineStyle_kDashed = 2,
00086   nsLineStyle_kDotted = 3
00087 } nsLineStyle;
00088 
00089 typedef enum
00090 {
00091   nsPenMode_kNone   = 0,
00092   nsPenMode_kInvert = 1
00093 } nsPenMode;
00094 
00095 
00096 // IID for the nsIRenderingContext interface
00097 #define NS_IRENDERING_CONTEXT_IID \
00098  { 0xd91f728b, 0xd7f4, 0x4e19,{0x8b, 0xdd, 0x98, 0x99, 0x3f, 0xdf, 0xec, 0xc6}}
00099 
00100 //----------------------------------------------------------------------
00101 
00102 // RenderingContext interface
00103 class nsIRenderingContext : public nsISupports
00104 {
00105 public:
00106   NS_DEFINE_STATIC_IID_ACCESSOR(NS_IRENDERING_CONTEXT_IID)
00107 
00108   //TBD: bind/unbind, transformation of scalars (hacky), 
00109   //potential drawmode for selection, polygons. MMP
00110 
00111   
00117   NS_IMETHOD Init(nsIDeviceContext* aContext, nsIWidget *aWidget) = 0;
00118 
00125   NS_IMETHOD Init(nsIDeviceContext* aContext, nsIDrawingSurface* aSurface) = 0;
00126 
00130   NS_IMETHOD Reset(void) = 0;
00131 
00136   NS_IMETHOD GetDeviceContext(nsIDeviceContext *& aDeviceContext) = 0;
00137 
00148   NS_IMETHOD LockDrawingSurface(PRInt32 aX, PRInt32 aY, PRUint32 aWidth, PRUint32 aHeight,
00149                                 void **aBits, PRInt32 *aStride, PRInt32 *aWidthBytes,
00150                                 PRUint32 aFlags) = 0;
00151 
00157   NS_IMETHOD UnlockDrawingSurface(void) = 0;
00158 
00165   NS_IMETHOD SelectOffScreenDrawingSurface(nsIDrawingSurface* aSurface) = 0;
00166 
00171   NS_IMETHOD GetDrawingSurface(nsIDrawingSurface* *aSurface) = 0;
00172 
00177   NS_IMETHOD GetHints(PRUint32& aResult) = 0;
00178 
00182   NS_IMETHOD PushState(void) = 0;
00183 
00187   NS_IMETHOD PopState(void) = 0;
00188 
00194   NS_IMETHOD IsVisibleRect(const nsRect& aRect, PRBool &aIsVisible) = 0;
00195 
00203   NS_IMETHOD SetClipRect(const nsRect& aRect, nsClipCombine aCombine) = 0;
00204 
00213   NS_IMETHOD GetClipRect(nsRect &aRect, PRBool &aHasLocalClip) = 0;
00214 
00220   NS_IMETHOD SetLineStyle(nsLineStyle aLineStyle) = 0;
00221 
00227   NS_IMETHOD GetLineStyle(nsLineStyle &aLineStyle) = 0;
00228 
00234   NS_IMETHOD GetPenMode(nsPenMode &aPenMode) =0;
00235 
00241   NS_IMETHOD SetPenMode(nsPenMode aPenMode) =0;
00242 
00243 
00251   NS_IMETHOD SetClipRegion(const nsIRegion& aRegion, nsClipCombine aCombine) = 0;
00252 
00260   NS_IMETHOD CopyClipRegion(nsIRegion &aRegion) = 0;
00261 
00269   NS_IMETHOD GetClipRegion(nsIRegion **aRegion) = 0;
00270 
00275   NS_IMETHOD SetColor(nscolor aColor) = 0;
00276 
00281   NS_IMETHOD GetColor(nscolor &aColor) const = 0;
00282 
00287   NS_IMETHOD SetFont(const nsFont& aFont, nsIAtom* aLangGroup) = 0;
00288 
00294   NS_IMETHOD SetFont(nsIFontMetrics *aFontMetrics) = 0;
00295 
00300   NS_IMETHOD GetFontMetrics(nsIFontMetrics *&aFontMetrics) = 0;
00301 
00307   NS_IMETHOD Translate(nscoord aX, nscoord aY) = 0;
00308 
00314   NS_IMETHOD Scale(float aSx, float aSy) = 0;
00315 
00316   struct PushedTranslation {
00317     float mSavedX, mSavedY;
00318   };
00319 
00320   class AutoPushTranslation {
00321     nsIRenderingContext* mCtx;
00322     PushedTranslation mPushed;
00323   public:
00324     AutoPushTranslation(nsIRenderingContext* aCtx, nscoord aX, nscoord aY)
00325       : mCtx(aCtx) {
00326       mCtx->PushTranslation(&mPushed);
00327       mCtx->Translate(aX, aY);
00328     }
00329     ~AutoPushTranslation() {
00330       mCtx->PopTranslation(&mPushed);
00331     }
00332   };
00333 
00334   NS_IMETHOD PushTranslation(PushedTranslation* aState) = 0;
00335 
00336   NS_IMETHOD PopTranslation(PushedTranslation* aState) = 0;
00337 
00342   NS_IMETHOD GetCurrentTransform(nsTransform2D *&aTransform) = 0;
00343 
00354   NS_IMETHOD CreateDrawingSurface(const nsRect& aBounds, PRUint32 aSurfFlags, nsIDrawingSurface* &aSurface) = 0;
00355 
00360   NS_IMETHOD DestroyDrawingSurface(nsIDrawingSurface* aDS) = 0;
00361 
00369   NS_IMETHOD DrawLine(nscoord aX0, nscoord aY0, nscoord aX1, nscoord aY1) = 0;
00370 
00376   NS_IMETHOD DrawPolyline(const nsPoint aPoints[], PRInt32 aNumPoints) = 0;
00377 
00382   NS_IMETHOD DrawRect(const nsRect& aRect) = 0;
00383 
00391   NS_IMETHOD DrawRect(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight) = 0;
00392 
00397   NS_IMETHOD FillRect(const nsRect& aRect) = 0;
00398 
00406   NS_IMETHOD FillRect(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight) = 0;
00407 
00412   NS_IMETHOD InvertRect(const nsRect& aRect) = 0;
00413 
00421   NS_IMETHOD InvertRect(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight) = 0;
00422 
00431   NS_IMETHOD FlushRect(const nsRect& aRect) = 0;
00432   NS_IMETHOD FlushRect(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight) = 0;
00433   
00439   NS_IMETHOD DrawPolygon(const nsPoint aPoints[], PRInt32 aNumPoints) = 0;
00440 
00446   NS_IMETHOD FillPolygon(const nsPoint aPoints[], PRInt32 aNumPoints) = 0;
00447 
00452   NS_IMETHOD DrawEllipse(const nsRect& aRect) = 0;
00453 
00461   NS_IMETHOD DrawEllipse(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight) = 0;
00462 
00467   NS_IMETHOD FillEllipse(const nsRect& aRect) = 0;
00468 
00476   NS_IMETHOD FillEllipse(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight) = 0;
00477 
00484   NS_IMETHOD DrawArc(const nsRect& aRect,
00485                      float aStartAngle, float aEndAngle) = 0;
00486 
00496   NS_IMETHOD DrawArc(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight,
00497                      float aStartAngle, float aEndAngle) = 0;
00498 
00505   NS_IMETHOD FillArc(const nsRect& aRect,
00506                      float aStartAngle, float aEndAngle) = 0;
00507 
00517   NS_IMETHOD FillArc(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight,
00518                      float aStartAngle, float aEndAngle) = 0;
00519 
00527   NS_IMETHOD GetWidth(char aC, nscoord &aWidth) = 0;
00528 
00539   NS_IMETHOD GetWidth(PRUnichar aC, nscoord &aWidth,
00540                       PRInt32 *aFontID = nsnull) = 0;
00541 
00552   NS_IMETHOD GetWidth(const nsString& aString, nscoord &aWidth,
00553                       PRInt32 *aFontID = nsnull) = 0;
00554 
00562   NS_IMETHOD GetWidth(const char* aString, nscoord& aWidth) = 0;
00563 
00572   NS_IMETHOD GetWidth(const char* aString, PRUint32 aLength,
00573                       nscoord& aWidth) = 0;
00574 
00586   NS_IMETHOD GetWidth(const PRUnichar *aString, PRUint32 aLength,
00587                       nscoord &aWidth, PRInt32 *aFontID = nsnull) = 0;
00588 
00600   NS_IMETHOD GetTextDimensions(const char* aString, PRUint32 aLength,
00601                                nsTextDimensions& aDimensions) = 0;
00602   NS_IMETHOD GetTextDimensions(const PRUnichar* aString, PRUint32 aLength,
00603                                nsTextDimensions& aDimensions, PRInt32* aFontID = nsnull) = 0;
00604 
00605 #if defined(_WIN32) || defined(XP_OS2) || defined(MOZ_X11) || defined(XP_BEOS)
00606 
00631   NS_IMETHOD GetTextDimensions(const char*       aString,
00632                                PRInt32           aLength,
00633                                PRInt32           aAvailWidth,
00634                                PRInt32*          aBreaks,
00635                                PRInt32           aNumBreaks,
00636                                nsTextDimensions& aDimensions,
00637                                PRInt32&          aNumCharsFit,
00638                                nsTextDimensions& aLastWordDimensions,
00639                                PRInt32*          aFontID = nsnull) = 0;
00640 
00641   NS_IMETHOD GetTextDimensions(const PRUnichar*  aString,
00642                                PRInt32           aLength,
00643                                PRInt32           aAvailWidth,
00644                                PRInt32*          aBreaks,
00645                                PRInt32           aNumBreaks,
00646                                nsTextDimensions& aDimensions,
00647                                PRInt32&          aNumCharsFit,
00648                                nsTextDimensions& aLastWordDimensions,
00649                                PRInt32*          aFontID = nsnull) = 0;
00650 #endif
00651 
00660   NS_IMETHOD DrawString(const char *aString, PRUint32 aLength,
00661                         nscoord aX, nscoord aY,
00662                         const nscoord* aSpacing = nsnull) = 0;
00663 
00675   NS_IMETHOD DrawString(const PRUnichar *aString, PRUint32 aLength,
00676                         nscoord aX, nscoord aY,
00677                         PRInt32 aFontID = -1,
00678                         const nscoord* aSpacing = nsnull) = 0;
00679 
00690   NS_IMETHOD DrawString(const nsString& aString, nscoord aX, nscoord aY,
00691                         PRInt32 aFontID = -1,
00692                         const nscoord* aSpacing = nsnull) = 0;
00693 
00702   NS_IMETHOD CopyOffScreenBits(nsIDrawingSurface* aSrcSurf, PRInt32 aSrcX, PRInt32 aSrcY,
00703                                const nsRect &aDestBounds, PRUint32 aCopyFlags) = 0;
00704   //~~~
00705   NS_IMETHOD RetrieveCurrentNativeGraphicData(void** ngd) = 0;
00706 
00707 
00721   NS_IMETHOD GetBackbuffer(const nsRect &aRequestedSize, const nsRect &aMaxSize, PRBool aForBlending, nsIDrawingSurface* &aBackbuffer) = 0;
00722 
00727   NS_IMETHOD ReleaseBackbuffer(void) = 0;
00728 
00733   NS_IMETHOD DestroyCachedBackbuffer(void) = 0;
00734 
00741   NS_IMETHOD UseBackbuffer(PRBool* aUseBackbuffer) = 0;
00742 
00743 
00744 #ifdef MOZ_MATHML
00745 
00752   NS_IMETHOD
00753   GetBoundingMetrics(const char*        aString,
00754                      PRUint32           aLength,
00755                      nsBoundingMetrics& aBoundingMetrics) = 0;
00766   NS_IMETHOD
00767   GetBoundingMetrics(const PRUnichar*   aString,
00768                      PRUint32           aLength,
00769                      nsBoundingMetrics& aBoundingMetrics,
00770                      PRInt32*           aFontID = nsnull) = 0;
00771 #endif
00772 
00773 
00778   NS_IMETHOD SetRightToLeftText(PRBool aIsRTL) = 0;
00779 
00789   NS_IMETHOD DrawImage(imgIContainer *aImage, const nsRect & aSrcRect, const nsRect & aDestRect) = 0;
00790 
00791   /*
00792    * Tiles an image over an area
00793    * @param aImage       Image to tile
00794    * @param aXImageStart x location where the origin (0,0) of the image starts
00795    * @param aYImageStart y location where the origin (0,0) of the image starts
00796    * @param aTargetRect  area to draw to
00797    */
00798   NS_IMETHOD DrawTile(imgIContainer *aImage,
00799                       nscoord aXImageStart, nscoord aYImageStart,
00800                       const nsRect * aTargetRect) = 0;
00801 
00802 
00821   NS_IMETHOD GetClusterInfo(const PRUnichar *aText,
00822                             PRUint32 aLength,
00823                             PRUint8 *aClusterStarts) = 0;
00824 
00840   virtual PRInt32 GetPosition(const PRUnichar *aText,
00841                               PRUint32 aLength,
00842                               nsPoint aPt) = 0;
00843 
00861   NS_IMETHOD GetRangeWidth(const PRUnichar *aText,
00862                            PRUint32 aLength,
00863                            PRUint32 aStart,
00864                            PRUint32 aEnd,
00865                            PRUint32 &aWidth) = 0;
00866 
00874   NS_IMETHOD GetRangeWidth(const char *aText,
00875                            PRUint32 aLength,
00876                            PRUint32 aStart,
00877                            PRUint32 aEnd,
00878                            PRUint32 &aWidth) = 0;
00879 
00895   NS_IMETHOD RenderEPS(const nsRect& aRect, FILE *aDataFile) = 0;
00896 };
00897 
00898 //modifiers for text rendering
00899 
00900 #define NS_DRAWSTRING_NORMAL            0x0
00901 #define NS_DRAWSTRING_UNDERLINE         0x1
00902 #define NS_DRAWSTRING_OVERLINE          0x2
00903 #define NS_DRAWSTRING_LINE_THROUGH      0x4
00904 
00905 // Bit values for GetHints
00906 
00913 #define NS_RENDERING_HINT_FAST_8BIT_TEXT   0x1
00914 
00919 #define NS_RENDERING_HINT_REMOTE_RENDERING 0x2
00920 
00925 #define NS_RENDERING_HINT_BIDI_REORDERING 0x4
00926 
00931 #define NS_RENDERING_HINT_ARABIC_SHAPING 0x8
00932 
00936 #define NS_RENDERING_HINT_FAST_MEASURE 0x10
00937 
00942 #define NS_RENDERING_HINT_TEXT_CLUSTERS 0x20
00943 
00950 #define NS_RENDERING_HINT_REORDER_SPACED_TEXT 0x40
00951 
00952 //flags for copy CopyOffScreenBits
00953 
00954 //when performing the blit, use the region, if any,
00955 //that exists in the source drawingsurface as a
00956 //blit mask.
00957 #define NS_COPYBITS_USE_SOURCE_CLIP_REGION  0x0001
00958 
00959 //transform the source offsets by the xform in the
00960 //rendering context
00961 #define NS_COPYBITS_XFORM_SOURCE_VALUES     0x0002
00962 
00963 //transform the destination rect by the xform in the
00964 //rendering context
00965 #define NS_COPYBITS_XFORM_DEST_VALUES       0x0004
00966 
00967 //this is basically a hack and is used by callers
00968 //who have selected an alternate drawing surface and
00969 //wish the copy to happen to that buffer rather than
00970 //the "front" buffer. i'm not proud of this. MMP
00971 //XXX: This is no longer needed by the XPCODE. It will
00972 //be removed once all of the platform specific nsRenderingContext's
00973 //stop using it.
00974 #define NS_COPYBITS_TO_BACK_BUFFER          0x0008
00975 
00976 /* Struct used to represent the overall extent of a string
00977    whose rendering may involve switching between different
00978    fonts that have different metrics.
00979 */
00980 struct nsTextDimensions {
00981   // max ascent amongst all the fonts needed to represent the string
00982   nscoord ascent;
00983 
00984   // max descent amongst all the fonts needed to represent the string
00985   nscoord descent;
00986 
00987   // width of the string
00988   nscoord width;
00989 
00990 
00991   nsTextDimensions()
00992   {
00993     Clear();
00994   }
00995 
00996   /* Set all member data to zero */
00997   void 
00998   Clear() {
00999     ascent = descent = width = 0;
01000   }
01001 
01002   /* Sum with another dimension */
01003   void 
01004   Combine(const nsTextDimensions& aOther) {
01005     if (ascent < aOther.ascent) ascent = aOther.ascent;
01006     if (descent < aOther.descent) descent = aOther.descent;   
01007     width += aOther.width;
01008   }
01009 };
01010 
01011 #ifdef MOZ_MATHML
01012 /* Struct used for accurate measurements of a string in order
01013    to allow precise positioning when processing MathML.
01014 */
01015 struct nsBoundingMetrics {
01016 
01018   // Metrics that _exactly_ enclose the text:
01019 
01020   // The character coordinate system is the one used on X Windows:
01021   // 1. The origin is located at the intersection of the baseline
01022   //    with the left of the character's cell.
01023   // 2. All horizontal bearings are oriented from left to right.
01024   // 3. The ascent is oriented from bottom to top (being 0 at the orgin).
01025   // 4. The descent is oriented from top to bottom (being 0 at the origin).
01026 
01027   // Note that Win32/Mac/PostScript use a different convention for
01028   // the descent (all vertical measurements are oriented from bottom
01029   // to top on these palatforms). Make sure to flip the sign of the
01030   // descent on these platforms for cross-platform compatibility.
01031 
01032   // Any of the following member variables listed here can have 
01033   // positive or negative value.
01034 
01035   nscoord leftBearing;
01036        /* The horizontal distance from the origin of the drawing
01037           operation to the left-most part of the drawn string. */
01038 
01039   nscoord rightBearing;
01040        /* The horizontal distance from the origin of the drawing
01041           operation to the right-most part of the drawn string.
01042           The _exact_ width of the string is therefore:
01043           rightBearing - leftBearing */
01044   
01045   nscoord ascent;
01046        /* The vertical distance from the origin of the drawing 
01047           operation to the top-most part of the drawn string. */
01048 
01049   nscoord descent;
01050        /* The vertical distance from the origin of the drawing 
01051           operation to the bottom-most part of the drawn string.
01052           The _exact_ height of the string is therefore:
01053           ascent + descent */
01054 
01056   // Metrics for placing other surrounding text:
01057 
01058   nscoord width;
01059        /* The horizontal distance from the origin of the drawing
01060           operation to the correct origin for drawing another string
01061           to follow the current one. Depending on the font, this
01062           could be greater than or less than the right bearing. */
01063 
01064   nsBoundingMetrics() {
01065     Clear();
01066   }
01067 
01069   // Utility methods and operators:
01070 
01071   /* Set all member data to zero */
01072   void 
01073   Clear() {
01074     leftBearing = rightBearing = 0;
01075     ascent = descent = width = 0;
01076   }
01077 
01078   /* Append another bounding metrics */
01079   /* Notice that leftBearing is not set. The user must set leftBearing on 
01080      initialization and (repeatedly) use this operator to append 
01081      other bounding metrics on the right.
01082    */
01083   void 
01084   operator += (const nsBoundingMetrics& bm) {
01085     if (ascent < bm.ascent) ascent = bm.ascent;
01086     if (descent < bm.descent) descent = bm.descent;   
01087     rightBearing = PR_MAX(rightBearing, width + bm.rightBearing);
01088     width += bm.width;
01089   }
01090 };
01091 #endif // MOZ_MATHML
01092 
01093 #endif /* nsIRenderingContext_h___ */