Methods Index

CDrawingContext

Heritage

Superclass: CStackable

Description

The CDrawingContext class serves as a wrapper to the XVT Portability Toolkit drawing protocol. It allows for use of the XVT-Power++ mathematical objects CPoint and CRect, and it takes advantage of drawing tools through the CEnvironment class.

The CDrawingContext class also factors out the need to set global units before converting to the XVT Portability Toolkit mathematical structures. CDrawingContext methods always assumes global, window relative coordinates.

Since CDrawingContext uses a stacking scheme, it is possible to call other methods that create CDrawingContext objects; when those methods go out of the scope, the previous drawing context is brought back into scope. This is important because it allows you to avoid reapplying the environment to the drawing window.

A drawing context is created on the stack, typically, within a CView-derived Draw method. When you construct the CDrawingContext, initializing it with the CView, the drawing context object creates a local copy of the view's environment. This is done so that changes can be made without affecting the shared environment. In addition, the drawing object sets the global units.

The following is an example of constructing a CDrawingContext object initialized with a CView (CMyView):

void CMyView::Draw(const CRect &theFrame)
{
	CView::Draw(theFrame);
	CDrawingContext aDC(this);				// makes a copy of
							// the environment
	aDC.DrawOval(GetGlobalFrame());
}

A drawing context does not have to be created relative to a CView, like this:

void CSomeClass::PaintSomething(void)
{
	CDrawingContext aDC(itsCWindow, CEnvironment());
	aDC.DrawRect(itsSize, 15, 15);																			// rounded rect
}

Protected Data Members

BOOLEAN itIsView; The flag for window or view usage
BOOLEAN itIsUpdateTools; The flag for updating tools
CView *itsView; The view
CEnvironment itsEnv; The current drawing environment
short isLocalQueueOverride Flag for determining if local or global region update policy is to be used
short isLocalRegionedQueue Are update regions being queued by local object
static short isRegionedQueue Are update regions being queued in general
RWOrdered itsInvalidateQueue List of invalidated regions (CRectRWC*)


`BOOLEAN`	`itIsView;`	The flag for window or view usage
`BOOLEAN`	`itIsUpdateTools;`	The flag for updating tools
`CView`	`*itsView;`	The view
`CEnvironment`	`itsEnv;`	The current drawing environment
`short`	`isLocalQueueOverride`	Flag for determining if local or global region update policy is to be used
`short`	`isLocalRegionedQueue`	Are update regions being queued by local object
`static`	`short isRegionedQueue`	Are update regions being queued in general
`RWOrdered`	`itsInvalidateQueue`	List of invalidated regions (`CRectRWC*`)

Public Methods

Constructor, Destructor, and Initializer Methods

CDrawingContext(CView *theView);

A constructor for drawing in the CWindow of a CView using the environment and UNITS of theView.

CDrawingContext(CWindow *theWindow, 
	const CEnvironment &theEnvironment);

A constructor for drawing in a window using theWindow's UNITS and environment.

virtual ~CDrawingContext();

A destructor. When a CDrawingContext object is deleted, the drawing state of the window returns to the state of the previous CDrawingContext on the stack. This allows for easy nesting of CDrawingContext usage.

Drawing Methods

void DrawLine(const CPoint &theStartPoint,
	const CPoint &theEndPoint,
	BOOLEAN theBegArrow = FALSE,
	BOOLEAN theEndArrow = FALSE);

Draws a line from theStartPoint to theEndPoint that has arrows as specified by theBegArrow and theEndArrow.

void DrawLine(const CPoint &theEndPoint,
	BOOLEAN theBegArrow = FALSE,
	BOOLEAN theEndArrow = FALSE);

Draws a line from the current line position to theEndPoint with arrows as specified by theBegArrow and theEndArrow. The current line position can be the position to which a line was drawn, or you can set it explicitly with the SetLinePosition method. The DrawLine method allows for easy drawing of connected lines, as follows:

	CDrawingContext aDC(aView);
	aDC.DrawLine(CPoint(0, 0), CPoint(100, 100));
	// The previous line could also be represented by
	//   aDC.SetLinePos(CPoint(0, 0));
	//   aDC.DrawLine(CPoint(100, 100));
	aDC.DrawLine(CPoint(125, 75));
	aDC.DrawLine(CPoint(125, 125));
	aDC.DrawLine(CPoint(75, 125));
	aDC.DrawLine(CPoint(100, 100));

void DrawIcon(int theIconId, const CPoint &theTopLeft);

Draws the icon with the resource ID of theIconId, and positions its top-left corner at the position specified by theTopLeft.

void DrawArc(const CRect &theFrame,
	const CPoint &theStartPnt,
	const CPoint &theEndPnt);

Draws an Arc that is a section of the perimeter of an oval bounded by theFrame. The arc is drawn counter-clockwise along the oval from theStartPoint to theEndPoint. If one (or both) of these points is not exactly on the oval, an imaginary line is drawn from the center of the bounding rectangle to the point, and the intersection of that line and the oval is used as the starting or stopping point.

void DrawPie(const CRect &theFrame,
	const CPoint &theStartPnt,
	const CPoint &theEndPnt);

Draws the section of the oval (a "pie slice") bounded by theFrame. The point of the pie slice is at the center of theFrame. The arc portion of the pie slice is drawn counter-clockwise along the oval from theStartPoint to theEndPoint. If one or both of these points is not exactly on the oval, an imaginary line is drawn from the center of the bounding rectangle to the point. Then, the intersection of that line and the oval is used as the starting or stopping point.

void DrawPolygon(const RWOrdered &thePoints,
	BOOLEAN thePolyIsFilled = TRUE);

Draws the polygon described by thePoints. The thePoints argument is an array of CPointRWC. If thePolyIsFilled argument is FALSE, the polygon is simply a collection of lines between thePoints. If thePolyIsFilled is TRUE, the polygon is a filled, closed shape. If the first and last entries in thePoints do not coincide, an additional side is drawn from the last point to the first. If any sides intersect, the determination of what is inside and what is outside is platform-specific.

void DrawText(const CStringRW &theText, 
	const CPoint &theBaseLine);

Draws the string in the window. The string drawn is indicated by theText, starting at the point of theBaseLine. The text's baseline is at theBaseLine. The V() and the left side of the first character start theBaseLine, H().

void DrawPicture(PICTURE thePict, 
	const CRect &theViewRegion);

Draws thePict intheViewRegion of the window. The PICTURE is expanded, reduced, or stretched to fit in the area indicated by theViewRegion.

void DrawRect(const CRect &theFrame,
	short theWidthRounded  = 0,	// w & h in pixels
	short theHeightRounded = 0);

Draws a rectangle represented by theFrame. If theWidthRounded and theHeightRounded are not 0, the corners of the rectangle are rounded. In this case, each corner of the rectangle is a quadrant of the oval that is of the width indicated by theWidthRounded and of the height indicated by theHeightRounded.

void DrawPixmap(XVT_PIXMAP thePixmap,
	const CRect &theSourceRegion,
	const CRect &theDestRegion);

Draws theSourceRegion of thePixmap in theDestRegion of the window. If the regions indicated by theSourceRegion and theDestRegion are not congruent, this method translates and scales the pixmap as necessary to fit in the destination rectangle.

void DrawImage(XVT_IMAGE theImage,
	const CRect &theSourceRegion,
	const CRect &theDestRegion);

Draws theSourceRegion of theImage in theDestRegion of the window. If the regions indicated by theSourceRegion and theDestRegion are not congruent, this method translates and scales the image as necessary to fit in the destination rectangle.

void DrawOval(const CRect &theFrame);

Draws an oval (ellipse) that is bounded by theFrame.

void DrawOutsetFrame(const CRect &theOuterFrame,
	int   theBorderWidth,	/* in pixels */
	COLOR theUpShadow,
	COLOR theDownShadow);

Draws a outset, "three dimensional" rectangle using the width indicated by theBorderWidth, and with the outer frame indicated by theOuterFrame. For an outset frame the theUpShadow is used to draw the upper and left sides of the frame. theDownShadow is used to draw the right and bottom sides of the frame.

void DrawInsetFrame(const CRect &theOuterFrame,
	int   theBorderWidth,	/* in pixels */
	COLOR theUpShadow,
	COLOR theDownShadow);

Draws an inset, three dimensional rectangle using the width indicated by theBorderWidth, and using the outer frame indicated by theOuterFrame. For an inset frame, this method uses the theDownShadow color to draw the upper and left sides of the frame. It uses theUpShadow color to draw the right and bottom sides of the frame.

void DrawOutsetText(
	const CStringRW& theText,
	const CPoint& theBaseline,
	COLOR theUpShadow   = COLOR_WHITE,
	COLOR theDownShadow = COLOR_GRAY);

Draws text that has a raised appearance.

void DrawInsetText(
	const CStringRW& theText,
	const CPoint& theBaseline,
	COLOR theUpShadow   = COLOR_WHITE,
	COLOR theDownShadow = COLOR_GRAY);

Draws text that has the appearance of being carved into the background.

State Methods

void SetLinePos(const CPoint &theLoc);

Moves the current pen position to the location indicated by theLoc. For an example of the usage of this method, see the DrawLine() method

void SetEnv(const CEnvironment &theEnvironment);

Sets the environment of the CDrawingContext.

CEnvironment & GetEnv(void);

Returns the environment of the CDrawingContext.

CEnvironment & operator () (void);

Returns the environment of the CDrawingContext.

void SetClip(const CRect &theClipFrame = MAXRect);

Sets the clipping region of the window to theClipFrame. If called with no arguments, the SetClip method resets the clipping region to the entire window (i.e., no clipping).

CRect GetClip(void);

Returns the clipping region of the window.

void SetCaretPos(const CPoint &theLoc);

Moves the window caret to the point specified by theLoc.

void SetCaretVisible(BOOLEAN isVisible = TRUE);

Sets the visibility of the window's caret.

void SetCaretSize(int theWidth, int theHeight);

Sets the width and height of the window's caret using the width and height indicated in pixels by theWidth and theHeight arguments respectively.

void ScrollRect(const CRect &theRegion, 
	int theHDist, 
	int theVDist);

Scrolls the pixels bounded by theRegion by theHDist pixels horizontally and by theVDist pixels vertically. The region of the screen exposed by the scroll is invalidated.

void InvalidateRect(const CRect &theRegion = MAXRect);

Invalidates the portion of the window indicated by theRegion. This method causes the specified portion of the window to be redrawn.

BOOLEAN IsUpdateNeeded(const CRect &theRegion);

Returns TRUE if the portion of the window indicated by theRegion needs to be redrawn.

Invalidate Methods

The following methods are used to invalidate many regions of a window at once. Some platforms, notably the Mac, can efficiently invalidate many discontiguous regions. However, other platforms work most efficiently when invalidating the sum of the regions: the following interface supports this notion. By default all regions are unioned (QueueInvalidate) and invalidated (FlushInvalidate) as a single frame, except on the Mac where each region is invalidated. This behavior may be overridden for all uses by calling SetRegionedQueue(). Also, there are cases where you will always want to send independent invalidates, but on a local basis. SetLocalRegionedQueue() will set the behavior locally to a CDrawingContext instance.

void QueueInvalidate( const CRect& theRect );

Queue invalidates frames.

void FlushInvalidate();

Sends all invalidates based on global and/or local invalidate queue.

void ClearInvalidate();

Clears current invalidate queue.

void SetLocalRegionedQueue( BOOLEAN isRegioned );

Locally overrides invalidate queue.

static BOOLEAN IsRegionedQueue();

Asks if FlushInvalidate() will globally queue invalidates or union them.

static void SetRegionedQueue( BOOLEAN isRegioned );

Sets global queue invalidate status. This is set by default to TRUE on the Mac and FALSE on all other platforms.

Protected Methods

Implementation Methods

void MakeCurrent(void);

Ensures that the window's UNITS and CEnvironment settings are current for the CDrawingContext.

virtual void DoUpdate(void);

Makes the window's UNITS and CEnvironment settings current when a nested CDrawingContext is destroyed.

Canceled Methods

The new and delete operators are overloaded to provide CStackable functionality:

CDrawingContext(const CDrawingContext &);
CDrawingContext& operator= (const CDrawingContext &);

[Classes] [Prev] [Next] [Methods]

support@xvt.com

CDrawingContext

CDrawingContext

Heritage

Description

Usage

Protected Data Members

Public Methods

Constructor, Destructor, and Initializer Methods

Drawing Methods

State Methods

Invalidate Methods

Protected Methods

Implementation Methods

Canceled Methods