cdc-class.md

---
title: "CDC Class"
description: "Learn more about: CDC Class"
ms.date: 11/19/2018
f1_keywords: ["CDC", "AFXWIN/CDC", "AFXWIN/CDC::CDC", "AFXWIN/CDC::AbortDoc", "AFXWIN/CDC::AbortPath", "AFXWIN/CDC::AddMetaFileComment", "AFXWIN/CDC::AlphaBlend", "AFXWIN/CDC::AngleArc", "AFXWIN/CDC::Arc", "AFXWIN/CDC::ArcTo", "AFXWIN/CDC::Attach", "AFXWIN/CDC::BeginPath", "AFXWIN/CDC::BitBlt", "AFXWIN/CDC::Chord", "AFXWIN/CDC::CloseFigure", "AFXWIN/CDC::CreateCompatibleDC", "AFXWIN/CDC::CreateDC", "AFXWIN/CDC::CreateIC", "AFXWIN/CDC::DeleteDC", "AFXWIN/CDC::DeleteTempMap", "AFXWIN/CDC::Detach", "AFXWIN/CDC::DPtoHIMETRIC", "AFXWIN/CDC::DPtoLP", "AFXWIN/CDC::Draw3dRect", "AFXWIN/CDC::DrawDragRect", "AFXWIN/CDC::DrawEdge", "AFXWIN/CDC::DrawEscape", "AFXWIN/CDC::DrawFocusRect", "AFXWIN/CDC::DrawFrameControl", "AFXWIN/CDC::DrawIcon", "AFXWIN/CDC::DrawState", "AFXWIN/CDC::DrawText", "AFXWIN/CDC::DrawTextEx", "AFXWIN/CDC::Ellipse", "AFXWIN/CDC::EndDoc", "AFXWIN/CDC::EndPage", "AFXWIN/CDC::EndPath", "AFXWIN/CDC::EnumObjects", "AFXWIN/CDC::Escape", "AFXWIN/CDC::ExcludeClipRect", "AFXWIN/CDC::ExcludeUpdateRgn", "AFXWIN/CDC::ExtFloodFill", "AFXWIN/CDC::ExtTextOut", "AFXWIN/CDC::FillPath", "AFXWIN/CDC::FillRect", "AFXWIN/CDC::FillRgn", "AFXWIN/CDC::FillSolidRect", "AFXWIN/CDC::FlattenPath", "AFXWIN/CDC::FloodFill", "AFXWIN/CDC::FrameRect", "AFXWIN/CDC::FrameRgn", "AFXWIN/CDC::FromHandle", "AFXWIN/CDC::GetArcDirection", "AFXWIN/CDC::GetAspectRatioFilter", "AFXWIN/CDC::GetBkColor", "AFXWIN/CDC::GetBkMode", "AFXWIN/CDC::GetBoundsRect", "AFXWIN/CDC::GetBrushOrg", "AFXWIN/CDC::GetCharABCWidths", "AFXWIN/CDC::GetCharABCWidthsI", "AFXWIN/CDC::GetCharacterPlacement", "AFXWIN/CDC::GetCharWidth", "AFXWIN/CDC::GetCharWidthI", "AFXWIN/CDC::GetClipBox", "AFXWIN/CDC::GetColorAdjustment", "AFXWIN/CDC::GetCurrentBitmap", "AFXWIN/CDC::GetCurrentBrush", "AFXWIN/CDC::GetCurrentFont", "AFXWIN/CDC::GetCurrentPalette", "AFXWIN/CDC::GetCurrentPen", "AFXWIN/CDC::GetCurrentPosition", "AFXWIN/CDC::GetDCBrushColor", "AFXWIN/CDC::GetDCPenColor", "AFXWIN/CDC::GetDeviceCaps", "AFXWIN/CDC::GetFontData", "AFXWIN/CDC::GetFontLanguageInfo", "AFXWIN/CDC::GetGlyphOutline", "AFXWIN/CDC::GetGraphicsMode", "AFXWIN/CDC::GetHalftoneBrush", "AFXWIN/CDC::GetKerningPairs", "AFXWIN/CDC::GetLayout", "AFXWIN/CDC::GetMapMode", "AFXWIN/CDC::GetMiterLimit", "AFXWIN/CDC::GetNearestColor", "AFXWIN/CDC::GetOutlineTextMetrics", "AFXWIN/CDC::GetOutputCharWidth", "AFXWIN/CDC::GetOutputTabbedTextExtent", "AFXWIN/CDC::GetOutputTextExtent", "AFXWIN/CDC::GetOutputTextMetrics", "AFXWIN/CDC::GetPath", "AFXWIN/CDC::GetPixel", "AFXWIN/CDC::GetPolyFillMode", "AFXWIN/CDC::GetROP2", "AFXWIN/CDC::GetSafeHdc", "AFXWIN/CDC::GetStretchBltMode", "AFXWIN/CDC::GetTabbedTextExtent", "AFXWIN/CDC::GetTextAlign", "AFXWIN/CDC::GetTextCharacterExtra", "AFXWIN/CDC::GetTextColor", "AFXWIN/CDC::GetTextExtent", "AFXWIN/CDC::GetTextExtentExPointI", "AFXWIN/CDC::GetTextExtentPointI", "AFXWIN/CDC::GetTextFace", "AFXWIN/CDC::GetTextMetrics", "AFXWIN/CDC::GetViewportExt", "AFXWIN/CDC::GetViewportOrg", "AFXWIN/CDC::GetWindow", "AFXWIN/CDC::GetWindowExt", "AFXWIN/CDC::GetWindowOrg", "AFXWIN/CDC::GetWorldTransform", "AFXWIN/CDC::GradientFill", "AFXWIN/CDC::GrayString", "AFXWIN/CDC::HIMETRICtoDP", "AFXWIN/CDC::HIMETRICtoLP", "AFXWIN/CDC::IntersectClipRect", "AFXWIN/CDC::InvertRect", "AFXWIN/CDC::InvertRgn", "AFXWIN/CDC::IsPrinting", "AFXWIN/CDC::LineTo", "AFXWIN/CDC::LPtoDP", "AFXWIN/CDC::LPtoHIMETRIC", "AFXWIN/CDC::MaskBlt", "AFXWIN/CDC::ModifyWorldTransform", "AFXWIN/CDC::MoveTo", "AFXWIN/CDC::OffsetClipRgn", "AFXWIN/CDC::OffsetViewportOrg", "AFXWIN/CDC::OffsetWindowOrg", "AFXWIN/CDC::PaintRgn", "AFXWIN/CDC::PatBlt", "AFXWIN/CDC::Pie", "AFXWIN/CDC::PlayMetaFile", "AFXWIN/CDC::PlgBlt", "AFXWIN/CDC::PolyBezier", "AFXWIN/CDC::PolyBezierTo", "AFXWIN/CDC::PolyDraw", "AFXWIN/CDC::Polygon", "AFXWIN/CDC::Polyline", "AFXWIN/CDC::PolylineTo", "AFXWIN/CDC::PolyPolygon", "AFXWIN/CDC::PolyPolyline", "AFXWIN/CDC::PtVisible", "AFXWIN/CDC::RealizePalette", "AFXWIN/CDC::Rectangle", "AFXWIN/CDC::RectVisible", "AFXWIN/CDC::ReleaseAttribDC", "AFXWIN/CDC::ReleaseOutputDC", "AFXWIN/CDC::ResetDC", "AFXWIN/CDC::RestoreDC", "AFXWIN/CDC::RoundRect", "AFXWIN/CDC::SaveDC", "AFXWIN/CDC::ScaleViewportExt", "AFXWIN/CDC::ScaleWindowExt", "AFXWIN/CDC::ScrollDC", "AFXWIN/CDC::SelectClipPath", "AFXWIN/CDC::SelectClipRgn", "AFXWIN/CDC::SelectObject", "AFXWIN/CDC::SelectPalette", "AFXWIN/CDC::SelectStockObject", "AFXWIN/CDC::SetAbortProc", "AFXWIN/CDC::SetArcDirection", "AFXWIN/CDC::SetAttribDC", "AFXWIN/CDC::SetBkColor", "AFXWIN/CDC::SetBkMode", "AFXWIN/CDC::SetBoundsRect", "AFXWIN/CDC::SetBrushOrg", "AFXWIN/CDC::SetColorAdjustment", "AFXWIN/CDC::SetDCBrushColor", "AFXWIN/CDC::SetDCPenColor", "AFXWIN/CDC::SetGraphicsMode", "AFXWIN/CDC::SetLayout", "AFXWIN/CDC::SetMapMode", "AFXWIN/CDC::SetMapperFlags", "AFXWIN/CDC::SetMiterLimit", "AFXWIN/CDC::SetOutputDC", "AFXWIN/CDC::SetPixel", "AFXWIN/CDC::SetPixelV", "AFXWIN/CDC::SetPolyFillMode", "AFXWIN/CDC::SetROP2", "AFXWIN/CDC::SetStretchBltMode", "AFXWIN/CDC::SetTextAlign", "AFXWIN/CDC::SetTextCharacterExtra", "AFXWIN/CDC::SetTextColor", "AFXWIN/CDC::SetTextJustification", "AFXWIN/CDC::SetViewportExt", "AFXWIN/CDC::SetViewportOrg", "AFXWIN/CDC::SetWindowExt", "AFXWIN/CDC::SetWindowOrg", "AFXWIN/CDC::SetWorldTransform", "AFXWIN/CDC::StartDoc", "AFXWIN/CDC::StartPage", "AFXWIN/CDC::StretchBlt", "AFXWIN/CDC::StrokeAndFillPath", "AFXWIN/CDC::StrokePath", "AFXWIN/CDC::TabbedTextOut", "AFXWIN/CDC::TextOut", "AFXWIN/CDC::TransparentBlt", "AFXWIN/CDC::UpdateColors", "AFXWIN/CDC::WidenPath", "AFXWIN/CDC::m_hAttribDC", "AFXWIN/CDC::m_hDC"]
helpviewer_keywords: ["CDC [MFC], CDC", "CDC [MFC], AbortDoc", "CDC [MFC], AbortPath", "CDC [MFC], AddMetaFileComment", "CDC [MFC], AlphaBlend", "CDC [MFC], AngleArc", "CDC [MFC], Arc", "CDC [MFC], ArcTo", "CDC [MFC], Attach", "CDC [MFC], BeginPath", "CDC [MFC], BitBlt", "CDC [MFC], Chord", "CDC [MFC], CloseFigure", "CDC [MFC], CreateCompatibleDC", "CDC [MFC], CreateDC", "CDC [MFC], CreateIC", "CDC [MFC], DeleteDC", "CDC [MFC], DeleteTempMap", "CDC [MFC], Detach", "CDC [MFC], DPtoHIMETRIC", "CDC [MFC], DPtoLP", "CDC [MFC], Draw3dRect", "CDC [MFC], DrawDragRect", "CDC [MFC], DrawEdge", "CDC [MFC], DrawEscape", "CDC [MFC], DrawFocusRect", "CDC [MFC], DrawFrameControl", "CDC [MFC], DrawIcon", "CDC [MFC], DrawState", "CDC [MFC], DrawText", "CDC [MFC], DrawTextEx", "CDC [MFC], Ellipse", "CDC [MFC], EndDoc", "CDC [MFC], EndPage", "CDC [MFC], EndPath", "CDC [MFC], EnumObjects", "CDC [MFC], Escape", "CDC [MFC], ExcludeClipRect", "CDC [MFC], ExcludeUpdateRgn", "CDC [MFC], ExtFloodFill", "CDC [MFC], ExtTextOut", "CDC [MFC], FillPath", "CDC [MFC], FillRect", "CDC [MFC], FillRgn", "CDC [MFC], FillSolidRect", "CDC [MFC], FlattenPath", "CDC [MFC], FloodFill", "CDC [MFC], FrameRect", "CDC [MFC], FrameRgn", "CDC [MFC], FromHandle", "CDC [MFC], GetArcDirection", "CDC [MFC], GetAspectRatioFilter", "CDC [MFC], GetBkColor", "CDC [MFC], GetBkMode", "CDC [MFC], GetBoundsRect", "CDC [MFC], GetBrushOrg", "CDC [MFC], GetCharABCWidths", "CDC [MFC], GetCharABCWidthsI", "CDC [MFC], GetCharacterPlacement", "CDC [MFC], GetCharWidth", "CDC [MFC], GetCharWidthI", "CDC [MFC], GetClipBox", "CDC [MFC], GetColorAdjustment", "CDC [MFC], GetCurrentBitmap", "CDC [MFC], GetCurrentBrush", "CDC [MFC], GetCurrentFont", "CDC [MFC], GetCurrentPalette", "CDC [MFC], GetCurrentPen", "CDC [MFC], GetCurrentPosition", "CDC [MFC], GetDCBrushColor", "CDC [MFC], GetDCPenColor", "CDC [MFC], GetDeviceCaps", "CDC [MFC], GetFontData", "CDC [MFC], GetFontLanguageInfo", "CDC [MFC], GetGlyphOutline", "CDC [MFC], GetGraphicsMode", "CDC [MFC], GetHalftoneBrush", "CDC [MFC], GetKerningPairs", "CDC [MFC], GetLayout", "CDC [MFC], GetMapMode", "CDC [MFC], GetMiterLimit", "CDC [MFC], GetNearestColor", "CDC [MFC], GetOutlineTextMetrics", "CDC [MFC], GetOutputCharWidth", "CDC [MFC], GetOutputTabbedTextExtent", "CDC [MFC], GetOutputTextExtent", "CDC [MFC], GetOutputTextMetrics", "CDC [MFC], GetPath", "CDC [MFC], GetPixel", "CDC [MFC], GetPolyFillMode", "CDC [MFC], GetROP2", "CDC [MFC], GetSafeHdc", "CDC [MFC], GetStretchBltMode", "CDC [MFC], GetTabbedTextExtent", "CDC [MFC], GetTextAlign", "CDC [MFC], GetTextCharacterExtra", "CDC [MFC], GetTextColor", "CDC [MFC], GetTextExtent", "CDC [MFC], GetTextExtentExPointI", "CDC [MFC], GetTextExtentPointI", "CDC [MFC], GetTextFace", "CDC [MFC], GetTextMetrics", "CDC [MFC], GetViewportExt", "CDC [MFC], GetViewportOrg", "CDC [MFC], GetWindow", "CDC [MFC], GetWindowExt", "CDC [MFC], GetWindowOrg", "CDC [MFC], GetWorldTransform", "CDC [MFC], GradientFill", "CDC [MFC], GrayString", "CDC [MFC], HIMETRICtoDP", "CDC [MFC], HIMETRICtoLP", "CDC [MFC], IntersectClipRect", "CDC [MFC], InvertRect", "CDC [MFC], InvertRgn", "CDC [MFC], IsPrinting", "CDC [MFC], LineTo", "CDC [MFC], LPtoDP", "CDC [MFC], LPtoHIMETRIC", "CDC [MFC], MaskBlt", "CDC [MFC], ModifyWorldTransform", "CDC [MFC], MoveTo", "CDC [MFC], OffsetClipRgn", "CDC [MFC], OffsetViewportOrg", "CDC [MFC], OffsetWindowOrg", "CDC [MFC], PaintRgn", "CDC [MFC], PatBlt", "CDC [MFC], Pie", "CDC [MFC], PlayMetaFile", "CDC [MFC], PlgBlt", "CDC [MFC], PolyBezier", "CDC [MFC], PolyBezierTo", "CDC [MFC], PolyDraw", "CDC [MFC], Polygon", "CDC [MFC], Polyline", "CDC [MFC], PolylineTo", "CDC [MFC], PolyPolygon", "CDC [MFC], PolyPolyline", "CDC [MFC], PtVisible", "CDC [MFC], RealizePalette", "CDC [MFC], Rectangle", "CDC [MFC], RectVisible", "CDC [MFC], ReleaseAttribDC", "CDC [MFC], ReleaseOutputDC", "CDC [MFC], ResetDC", "CDC [MFC], RestoreDC", "CDC [MFC], RoundRect", "CDC [MFC], SaveDC", "CDC [MFC], ScaleViewportExt", "CDC [MFC], ScaleWindowExt", "CDC [MFC], ScrollDC", "CDC [MFC], SelectClipPath", "CDC [MFC], SelectClipRgn", "CDC [MFC], SelectObject", "CDC [MFC], SelectPalette", "CDC [MFC], SelectStockObject", "CDC [MFC], SetAbortProc", "CDC [MFC], SetArcDirection", "CDC [MFC], SetAttribDC", "CDC [MFC], SetBkColor", "CDC [MFC], SetBkMode", "CDC [MFC], SetBoundsRect", "CDC [MFC], SetBrushOrg", "CDC [MFC], SetColorAdjustment", "CDC [MFC], SetDCBrushColor", "CDC [MFC], SetDCPenColor", "CDC [MFC], SetGraphicsMode", "CDC [MFC], SetLayout", "CDC [MFC], SetMapMode", "CDC [MFC], SetMapperFlags", "CDC [MFC], SetMiterLimit", "CDC [MFC], SetOutputDC", "CDC [MFC], SetPixel", "CDC [MFC], SetPixelV", "CDC [MFC], SetPolyFillMode", "CDC [MFC], SetROP2", "CDC [MFC], SetStretchBltMode", "CDC [MFC], SetTextAlign", "CDC [MFC], SetTextCharacterExtra", "CDC [MFC], SetTextColor", "CDC [MFC], SetTextJustification", "CDC [MFC], SetViewportExt", "CDC [MFC], SetViewportOrg", "CDC [MFC], SetWindowExt", "CDC [MFC], SetWindowOrg", "CDC [MFC], SetWorldTransform", "CDC [MFC], StartDoc", "CDC [MFC], StartPage", "CDC [MFC], StretchBlt", "CDC [MFC], StrokeAndFillPath", "CDC [MFC], StrokePath", "CDC [MFC], TabbedTextOut", "CDC [MFC], TextOut", "CDC [MFC], TransparentBlt", "CDC [MFC], UpdateColors", "CDC [MFC], WidenPath", "CDC [MFC], m_hAttribDC", "CDC [MFC], m_hDC"]
---
# `CDC` Class

>[!NOTE]
> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation.

Defines a class of device-context objects.

## Syntax

```cpp
class CDC : public CObject
```

## Members

### Public Constructors

|Name|Description|
|----------|-----------------|
|[`CDC::CDC`](#cdc)|Constructs a `CDC` object.|

### Public Methods

|Name|Description|
|----------|-----------------|
|[`CDC::AbortDoc`](#abortdoc)|Terminates the current print job, erasing everything the application has written to the device since the last call of the `StartDoc` member function.|
|[`CDC::AbortPath`](#abortpath)|Closes and discards any paths in the device context.|
|[`CDC::AddMetaFileComment`](#addmetafilecomment)|Copies the comment from a buffer into a specified enhanced-format metafile.|
|[`CDC::AlphaBlend`](#alphablend)|Displays bitmaps that have transparent or semitransparent pixels.|
|[`CDC::AngleArc`](#anglearc)|Draws a line segment and an arc, and moves the current position to the ending point of the arc.|
|[`CDC::Arc`](#arc)|Draws an elliptical arc.|
|[`CDC::ArcTo`](#arcto)|Draws an elliptical arc. This function is similar to `Arc`, except that the current position is updated.|
|[`CDC::Attach`](#attach)|Attaches a Windows device context to this `CDC` object.|
|[`CDC::BeginPath`](#beginpath)|Opens a path bracket in the device context.|
|[`CDC::BitBlt`](#bitblt)|Copies a bitmap from a specified device context.|
|[`CDC::Chord`](#chord)|Draws a chord (a closed figure bounded by the intersection of an ellipse and a line segment).|
|[`CDC::CloseFigure`](#closefigure)|Closes an open figure in a path.|
|[`CDC::CreateCompatibleDC`](#createcompatibledc)|Creates a memory-device context that is compatible with another device context. You can use it to prepare images in memory.|
|[`CDC::CreateDC`](#createdc)|Creates a device context for a specific device.|
|[`CDC::CreateIC`](#createic)|Creates an information context for a specific device. This provides a fast way to get information about the device without creating a device context.|
|[`CDC::DeleteDC`](#deletedc)|Deletes the Windows device context associated with this `CDC` object.|
|[`CDC::DeleteTempMap`](#deletetempmap)|Called by the `CWinApp` idle-time handler to delete any temporary `CDC` object created by `FromHandle`. Also detaches the device context.|
|[`CDC::Detach`](#detach)|Detaches the Windows device context from this `CDC` object.|
|[`CDC::DPtoHIMETRIC`](#dptohimetric)|Converts device units into `HIMETRIC` units.|
|[`CDC::DPtoLP`](#dptolp)|Converts device units into logical units.|
|[`CDC::Draw3dRect`](#draw3drect)|Draws a three-dimensional rectangle.|
|[`CDC::DrawDragRect`](#drawdragrect)|Erases and redraws a rectangle as it's dragged.|
|[`CDC::DrawEdge`](#drawedge)|Draws the edges of a rectangle.|
|[`CDC::DrawEscape`](#drawescape)|Accesses drawing capabilities of a video display that aren't directly available through the graphics device interface (GDI).|
|[`CDC::DrawFocusRect`](#drawfocusrect)|Draws a rectangle in the style used to indicate focus.|
|[`CDC::DrawFrameControl`](#drawframecontrol)|Draw a frame control.|
|[`CDC::DrawIcon`](#drawicon)|Draws an icon.|
|[`CDC::DrawState`](#drawstate)|Displays an image and applies a visual effect to indicate a state.|
|[`CDC::DrawText`](#drawtext)|Draws formatted text in the specified rectangle.|
|[`CDC::DrawTextEx`](#drawtextex)|Draws formatted text in the specified rectangle using other formats.|
|[`CDC::Ellipse`](#ellipse)|Draws an ellipse.|
|[`CDC::EndDoc`](#enddoc)|Ends a print job started by the `StartDoc` member function.|
|[`CDC::EndPage`](#endpage)|Informs the device driver that a page is ending.|
|[`CDC::EndPath`](#endpath)|Closes a path bracket and selects the path defined by the bracket into the device context.|
|[`CDC::EnumObjects`](#enumobjects)|Enumerates the pens and brushes available in a device context.|
|[`CDC::Escape`](#escape)|Allows applications to access facilities that aren't directly available from a particular device through GDI. Also allows access to Windows escape functions. Escape calls made by an application are translated and sent to the device driver.|
|[`CDC::ExcludeClipRect`](#excludecliprect)|Creates a new clipping region that consists of the existing clipping region minus the specified rectangle.|
|[`CDC::ExcludeUpdateRgn`](#excludeupdatergn)|Prevents drawing within invalid areas of a window by excluding an updated region in the window from a clipping region.|
|[`CDC::ExtFloodFill`](#extfloodfill)|Fills an area with the current brush. Provides more flexibility than the [`CDC::FloodFill`](#floodfill) member function.|
|[`CDC::ExtTextOut`](#exttextout)|Writes a character string within a rectangular region using the currently selected font.|
|[`CDC::FillPath`](#fillpath)|Closes any open figures in the current path and fills the path's interior by using the current brush and polygon-filling mode.|
|[`CDC::FillRect`](#fillrect)|Fills a given rectangle by using a specific brush.|
|[`CDC::FillRgn`](#fillrgn)|Fills a specific region with the specified brush.|
|[`CDC::FillSolidRect`](#fillsolidrect)|Fills a rectangle with a solid color.|
|[`CDC::FlattenPath`](#flattenpath)|Transforms any curves in the path selected into the current device context, and turns each curve into a sequence of lines.|
|[`CDC::FloodFill`](#floodfill)|Fills an area with the current brush.|
|[`CDC::FrameRect`](#framerect)|Draws a border around a rectangle.|
|[`CDC::FrameRgn`](#framergn)|Draws a border around a specific region using a brush.|
|[`CDC::FromHandle`](#fromhandle)|Returns a pointer to a `CDC` object when given a handle to a device context. If a `CDC` object isn't attached to the handle, a temporary `CDC` object is created and attached.|
|[`CDC::GetArcDirection`](#getarcdirection)|Returns the current arc direction for the device context.|
|[`CDC::GetAspectRatioFilter`](#getaspectratiofilter)|Retrieves the setting for the current aspect-ratio filter.|
|[`CDC::GetBkColor`](#getbkcolor)|Retrieves the current background color.|
|[`CDC::GetBkMode`](#getbkmode)|Retrieves the background mode.|
|[`CDC::GetBoundsRect`](#getboundsrect)|Returns the current accumulated bounding rectangle for the specified device context.|
|[`CDC::GetBrushOrg`](#getbrushorg)|Retrieves the origin of the current brush.|
|[`CDC::GetCharABCWidths`](#getcharabcwidths)|Retrieves the widths, in logical units, of consecutive characters in a given range from the current font.|
|[`CDC::GetCharABCWidthsI`](#getcharabcwidthsi)|Retrieves the widths, in logical units, of consecutive glyph indices in a specified range from the current TrueType font.|
|[`CDC::GetCharacterPlacement`](#getcharacterplacement)|Retrieves various types of information on a character string.|
|[`CDC::GetCharWidth`](#getcharwidth)|Retrieves the fractional widths of consecutive characters in a given range from the current font.|
|[`CDC::GetCharWidthI`](#getcharwidthi)|Retrieves the widths, in logical coordinates, of consecutive glyph indices in a specified range from the current font.|
|[`CDC::GetClipBox`](#getclipbox)|Retrieves the dimensions of the tightest bounding rectangle around the current clipping boundary.|
|[`CDC::GetColorAdjustment`](#getcoloradjustment)|Retrieves the color adjustment values for the device context.|
|[`CDC::GetCurrentBitmap`](#getcurrentbitmap)|Returns a pointer to the currently selected `CBitmap` object.|
|[`CDC::GetCurrentBrush`](#getcurrentbrush)|Returns a pointer to the currently selected `CBrush` object.|
|[`CDC::GetCurrentFont`](#getcurrentfont)|Returns a pointer to the currently selected `CFont` object.|
|[`CDC::GetCurrentPalette`](#getcurrentpalette)|Returns a pointer to the currently selected `CPalette` object.|
|[`CDC::GetCurrentPen`](#getcurrentpen)|Returns a pointer to the currently selected `CPen` object.|
|[`CDC::GetCurrentPosition`](#getcurrentposition)|Retrieves the current position of the pen (in logical coordinates).|
|[`CDC::GetDCBrushColor`](#getdcbrushcolor)|Retrieves the current brush color.|
|[`CDC::GetDCPenColor`](#getdcpencolor)|Retrieves the current pen color.|
|[`CDC::GetDeviceCaps`](#getdevicecaps)|Retrieves a specified kind of device-specific information about a given display device's capabilities.|
|[`CDC::GetFontData`](#getfontdata)|Retrieves font metric information from a scalable font file. The information to retrieve is identified by specifying an offset into the font file and the length of the information to return.|
|[`CDC::GetFontLanguageInfo`](#getfontlanguageinfo)|Returns information about the currently selected font for the specified display context.|
|[`CDC::GetGlyphOutline`](#getglyphoutline)|Retrieves the outline curve or bitmap for an outline character in the current font.|
|[`CDC::GetGraphicsMode`](#getgraphicsmode)|Retrieves the current graphics mode for the specified device context.|
|[`CDC::GetHalftoneBrush`](#gethalftonebrush)|Retrieves a halftone brush.|
|[`CDC::GetKerningPairs`](#getkerningpairs)|Retrieves the character kerning pairs for the font that is currently selected in the specified device context.|
|[`CDC::GetLayout`](#getlayout)|Retrieves the layout of a device context (DC). The layout can be either left to right (default) or right to left (mirrored).|
|[`CDC::GetMapMode`](#getmapmode)|Retrieves the current mapping mode.|
|[`CDC::GetMiterLimit`](#getmiterlimit)|Returns the miter limit for the device context.|
|[`CDC::GetNearestColor`](#getnearestcolor)|Retrieves the closest logical color to a specified logical color that the given device can represent.|
|[`CDC::GetOutlineTextMetrics`](#getoutlinetextmetrics)|Retrieves font metric information for TrueType fonts.|
|[`CDC::GetOutputCharWidth`](#getoutputcharwidth)|Retrieves the widths of individual characters in a consecutive group of characters from the current font using the output device context.|
|[`CDC::GetOutputTabbedTextExtent`](#getoutputtabbedtextextent)|Computes the width and height of a character string on the output device context.|
|[`CDC::GetOutputTextExtent`](#getoutputtextextent)|Computes the width and height of a line of text on the output device context using the current font to determine the dimensions.|
|[`CDC::GetOutputTextMetrics`](#getoutputtextmetrics)|Retrieves the metrics for the current font from the output device context.|
|[`CDC::GetPath`](#getpath)|Retrieves the coordinates defining the endpoints of lines and the control points of curves found in the path that is selected into the device context.|
|[`CDC::GetPixel`](#getpixel)|Retrieves the RGB color value of the pixel at the specified point.|
|[`CDC::GetPolyFillMode`](#getpolyfillmode)|Retrieves the current polygon-filling mode.|
|[`CDC::GetROP2`](#getrop2)|Retrieves the current drawing mode.|
|[`CDC::GetSafeHdc`](#getsafehdc)|Returns [`CDC::m_hDC`](#m_hdc), the output device context.|
|[`CDC::GetStretchBltMode`](#getstretchbltmode)|Retrieves the current bitmap-stretching mode.|
|[`CDC::GetTabbedTextExtent`](#gettabbedtextextent)|Computes the width and height of a character string on the attribute device context.|
|[`CDC::GetTextAlign`](#gettextalign)|Retrieves the text-alignment flags.|
|[`CDC::GetTextCharacterExtra`](#gettextcharacterextra)|Retrieves the current setting for the amount of intercharacter spacing.|
|[`CDC::GetTextColor`](#gettextcolor)|Retrieves the current text color.|
|[`CDC::GetTextExtent`](#gettextextent)|Computes the width and height of a line of text on the attribute device context using the current font to determine the dimensions.|
|[`CDC::GetTextExtentExPointI`](#gettextextentexpointi)|Retrieves the number of characters in a specified string that will fit within a specified space and fills an array with the text extent for each of those characters.|
|[`CDC::GetTextExtentPointI`](#gettextextentpointi)|Retrieves the width and height of the specified array of glyph indices.|
|[`CDC::GetTextFace`](#gettextface)|Copies the typeface name of the current font into a buffer as a null-terminated string.|
|[`CDC::GetTextMetrics`](#gettextmetrics)|Retrieves the metrics for the current font from the attribute device context.|
|[`CDC::GetViewportExt`](#getviewportext)|Retrieves the x- and y-extents of the viewport.|
|[`CDC::GetViewportOrg`](#getviewportorg)|Retrieves the x- and y-coordinates of the viewport origin.|
|[`CDC::GetWindow`](#getwindow)|Returns the window associated with the display device context.|
|[`CDC::GetWindowExt`](#getwindowext)|Retrieves the x- and y-extents of the associated window.|
|[`CDC::GetWindowOrg`](#getwindoworg)|Retrieves the x- and y-coordinates of the origin of the associated window.|
|[`CDC::GetWorldTransform`](#getworldtransform)|Retrieves the current world-space to page-space transformation.|
|[`CDC::GradientFill`](#gradientfill)|Fills rectangle and triangle structures with a gradating color.|
|[`CDC::GrayString`](#graystring)|Draws dimmed (grayed) text at the given location.|
|[`CDC::HIMETRICtoDP`](#himetrictodp)|Converts HIMETRIC units into device units.|
|[`CDC::HIMETRICtoLP`](#himetrictolp)|Converts HIMETRIC units into logical units.|
|[`CDC::IntersectClipRect`](#intersectcliprect)|Creates a new clipping region by forming the intersection of the current region and a rectangle.|
|[`CDC::InvertRect`](#invertrect)|Inverts the contents of a rectangle.|
|[`CDC::InvertRgn`](#invertrgn)|Inverts the colors in a region.|
|[`CDC::IsPrinting`](#isprinting)|Determines whether the device context is being used for printing.|
|[`CDC::LineTo`](#lineto)|Draws a line from the current position up to, but not including, a point.|
|[`CDC::LPtoDP`](#lptodp)|Converts logical units into device units.|
|[`CDC::LPtoHIMETRIC`](#lptohimetric)|Converts logical units into HIMETRIC units.|
|[`CDC::MaskBlt`](#maskblt)|Combines the color data for the source and destination bitmaps using the given mask and raster operation.|
|[`CDC::ModifyWorldTransform`](#modifyworldtransform)|Changes the world transformation for a device context using the specified mode.|
|[`CDC::MoveTo`](#moveto)|Moves the current position.|
|[`CDC::OffsetClipRgn`](#offsetcliprgn)|Moves the clipping region of the given device.|
|[`CDC::OffsetViewportOrg`](#offsetviewportorg)|Modifies the viewport origin relative to the coordinates of the current viewport origin.|
|[`CDC::OffsetWindowOrg`](#offsetwindoworg)|Modifies the window origin relative to the coordinates of the current window origin.|
|[`CDC::PaintRgn`](#paintrgn)|Fills a region with the selected brush.|
|[`CDC::PatBlt`](#patblt)|Creates a bit pattern.|
|[`CDC::Pie`](#pie)|Draws a pie-shaped wedge.|
|[`CDC::PlayMetaFile`](#playmetafile)|Plays the contents of the specified metafile on the given device. The enhanced version of `PlayMetaFile` displays the picture stored in the given enhanced-format metafile. The metafile can be played any number of times.|
|[`CDC::PlgBlt`](#plgblt)|Performs a bit-block transfer of the bits of color data from the specified rectangle in the source device context to the specified parallelogram in the given device context.|
|[`CDC::PolyBezier`](#polybezier)|Draws one or more Bzier splines. The current position isn't used or updated.|
|[`CDC::PolyBezierTo`](#polybezierto)|Draws one or more Bzier splines, and moves the current position to the ending point of the last Bzier spline.|
|[`CDC::PolyDraw`](#polydraw)|Draws a set of line segments and Bzier splines. This function updates the current position.|
|[`CDC::Polygon`](#polygon)|Draws a polygon consisting of two or more points (vertices) connected by lines.|
|[`CDC::Polyline`](#polyline)|Draws a set of line segments connecting the specified points.|
|[`CDC::PolylineTo`](#polylineto)|Draws one or more straight lines and moves the current position to the ending point of the last line.|
|[`CDC::PolyPolygon`](#polypolygon)|Creates two or more polygons that are filled using the current polygon-filling mode. The polygons may be disjoint or they may overlap.|
|[`CDC::PolyPolyline`](#polypolyline)|Draws multiple series of connected line segments. The current position isn't used or updated by this function.|
|[`CDC::PtVisible`](#ptvisible)|Specifies whether the given point is within the clipping region.|
|[`CDC::RealizePalette`](#realizepalette)|Maps palette entries in the current logical palette to the system palette.|
|[`CDC::Rectangle`](#rectangle)|Draws a rectangle using the current pen and fills it using the current brush.|
|[`CDC::RectVisible`](#rectvisible)|Determines whether any part of the given rectangle lies within the clipping region.|
|[`CDC::ReleaseAttribDC`](#releaseattribdc)|Releases `m_hAttribDC`, the attribute device context.|
|[`CDC::ReleaseOutputDC`](#releaseoutputdc)|Releases `m_hDC`, the output device context.|
|[`CDC::ResetDC`](#resetdc)|Updates the `m_hAttribDC` device context.|
|[`CDC::RestoreDC`](#restoredc)|Restores the device context to a previous state saved with `SaveDC`.|
|[`CDC::RoundRect`](#roundrect)|Draws a rectangle with rounded corners using the current pen and filled using the current brush.|
|[`CDC::SaveDC`](#savedc)|Saves the current state of the device context.|
|[`CDC::ScaleViewportExt`](#scaleviewportext)|Modifies the viewport extent relative to the current values.|
|[`CDC::ScaleWindowExt`](#scalewindowext)|Modifies the window extents relative to the current values.|
|[`CDC::ScrollDC`](#scrolldc)|Scrolls a rectangle of bits horizontally and vertically.|
|[`CDC::SelectClipPath`](#selectclippath)|Selects the current path as a clipping region for the device context, combining the new region with any existing clipping region by using the specified mode.|
|[`CDC::SelectClipRgn`](#selectcliprgn)|Combines the given region with the current clipping region by using the specified mode.|
|[`CDC::SelectObject`](#selectobject)|Selects a GDI drawing object such as a pen.|
|[`CDC::SelectPalette`](#selectpalette)|Selects the logical palette.|
|[`CDC::SelectStockObject`](#selectstockobject)|Selects one of the predefined stock pens, brushes, or fonts provided by Windows.|
|[`CDC::SetAbortProc`](#setabortproc)|Sets a programmer-supplied callback function that Windows calls if a print job must be aborted.|
|[`CDC::SetArcDirection`](#setarcdirection)|Sets the drawing direction to be used for arc and rectangle functions.|
|[`CDC::SetAttribDC`](#setattribdc)|Sets `m_hAttribDC`, the attribute device context.|
|[`CDC::SetBkColor`](#setbkcolor)|Sets the current background color.|
|[`CDC::SetBkMode`](#setbkmode)|Sets the background mode.|
|[`CDC::SetBoundsRect`](#setboundsrect)|Controls the accumulation of bounding-rectangle information for the specified device context.|
|[`CDC::SetBrushOrg`](#setbrushorg)|Specifies the origin for the next brush selected into a device context.|
|[`CDC::SetColorAdjustment`](#setcoloradjustment)|Sets the color adjustment values for the device context using the specified values.|
|[`CDC::SetDCBrushColor`](#setdcbrushcolor)|Sets the current brush color.|
|[`CDC::SetDCPenColor`](#setdcpencolor)|Sets the current pen color.|
|[`CDC::SetGraphicsMode`](#setgraphicsmode)|Sets the current graphics mode for the specified device context.|
|[`CDC::SetLayout`](#setlayout)|Changes the layout of a device context (DC).|
|[`CDC::SetMapMode`](#setmapmode)|Sets the current mapping mode.|
|[`CDC::SetMapperFlags`](#setmapperflags)|Alters the algorithm that the font mapper uses when it maps logical fonts to physical fonts.|
|[`CDC::SetMiterLimit`](#setmiterlimit)|Sets the limit for the length of miter joins for the device context.|
|[`CDC::SetOutputDC`](#setoutputdc)|Sets `m_hDC`, the output device context.|
|[`CDC::SetPixel`](#setpixel)|Sets the pixel at the specified point to the closest approximation of the specified color.|
|[`CDC::SetPixelV`](#setpixelv)|Sets the pixel at the specified coordinates to the closest approximation of the specified color. `SetPixelV` is faster than `SetPixel` because it doesn't need to return the color value of the point painted.|
|[`CDC::SetPolyFillMode`](#setpolyfillmode)|Sets the polygon-filling mode.|
|[`CDC::SetROP2`](#setrop2)|Sets the current drawing mode.|
|[`CDC::SetStretchBltMode`](#setstretchbltmode)|Sets the bitmap-stretching mode.|
|[`CDC::SetTextAlign`](#settextalign)|Sets the text-alignment flags.|
|[`CDC::SetTextCharacterExtra`](#settextcharacterextra)|Sets the amount of intercharacter spacing.|
|[`CDC::SetTextColor`](#settextcolor)|Sets the text color.|
|[`CDC::SetTextJustification`](#settextjustification)|Adds space to the break characters in a string.|
|[`CDC::SetViewportExt`](#setviewportext)|Sets the x- and y-extents of the viewport.|
|[`CDC::SetViewportOrg`](#setviewportorg)|Sets the viewport origin.|
|[`CDC::SetWindowExt`](#setwindowext)|Sets the x- and y-extents of the associated window.|
|[`CDC::SetWindowOrg`](#setwindoworg)|Sets the window origin of the device context.|
|[`CDC::SetWorldTransform`](#setworldtransform)|Sets the current world-space to page-space transformation.|
|[`CDC::StartDoc`](#startdoc)|Informs the device driver that a new print job is starting.|
|[`CDC::StartPage`](#startpage)|Informs the device driver that a new page is starting.|
|[`CDC::StretchBlt`](#stretchblt)|Moves a bitmap from a source rectangle and device into a destination rectangle, stretching or compressing the bitmap if necessary to fit the dimensions of the destination rectangle.|
|[`CDC::StrokeAndFillPath`](#strokeandfillpath)|Closes any open figures in a path, strikes the outline of the path by using the current pen, and fills its interior by using the current brush.|
|[`CDC::StrokePath`](#strokepath)|Renders the specified path by using the current pen.|
|[`CDC::TabbedTextOut`](#tabbedtextout)|Writes a character string at a specified location, expanding tabs to the values specified in an array of tab-stop positions.|
|[`CDC::TextOut`](#textout)|Writes a character string at a specified location using the currently selected font.|
|[`CDC::TransparentBlt`](#transparentblt)|Transfers a bit-block of color data from the specified source device context into a destination device context, rendering a specified color transparent in the transfer.|
|[`CDC::UpdateColors`](#updatecolors)|Updates the client area of the device context by matching the current colors in the client area to the system palette on a pixel-by-pixel basis.|
|[`CDC::WidenPath`](#widenpath)|Redefines the current path as the area that would be painted if the path were stroked using the pen currently selected into the device context.|

### Public Operators

|Name|Description|
|----------|-----------------|
|[`CDC::operator HDC`](#operator_hdc)|Retrieves the handle of the device context.|

### Public Data Members

|Name|Description|
|----------|-----------------|
|[`CDC::m_hAttribDC`](#m_hattribdc)|The attribute-device context used by this `CDC` object.|
|[`CDC::m_hDC`](#m_hdc)|The output-device context used by this `CDC` object.|

## Remarks

The `CDC` object provides member functions for working with a device context, such as a display or printer, and members for working with a display context associated with the client area of a window.

Do all drawing through the member functions of a `CDC` object. The class provides member functions for device-context operations, working with drawing tools, type-safe graphics device interface (GDI) object selection, and working with colors and palettes. It also provides member functions for getting and setting drawing attributes, mapping, working with the viewport, working with the window extent, converting coordinates, working with regions, clipping, drawing lines, and drawing simple shapes, ellipses, and polygons. Member functions are also provided for drawing text, working with fonts, using printer escapes, scrolling, and playing metafiles.

To use a `CDC` object, construct it, and then call its member functions that parallel Windows functions that use device contexts.

> [!NOTE]
> Under Windows 95/98, all screen coordinates are limited to 16 bits. Therefore, an **`int`** passed to a `CDC` member function must lie in the range -32768 to 32767.

For specific uses, the Microsoft Foundation Class Library provides several classes derived from `CDC` . `CPaintDC` encapsulates calls to `BeginPaint` and `EndPaint`. `CClientDC` manages a display context associated with a window's client area. `CWindowDC` manages a display context associated with an entire window, including its frame and controls. `CMetaFileDC` associates a device context with a metafile.

`CDC` provides two member functions, [`GetLayout`](#getlayout) and [`SetLayout`](#setlayout), for reversing the layout of a device context, which doesn't inherit its layout from a window. Such right-to-left orientation is necessary for applications written for cultures, such as Arabic or Hebrew, where the character layout isn't the European standard.

`CDC` contains two device contexts, [`m_hDC`](#m_hdc) and [`m_hAttribDC`](#m_hattribdc), which, on creation of a `CDC` object, refer to the same device. `CDC` directs all output GDI calls to `m_hDC` and most attribute GDI calls to `m_hAttribDC`. (An example of an attribute call is `GetTextColor`, while `SetTextColor` is an output call.)

For example, the framework uses these two device contexts to implement a `CMetaFileDC` object that will send output to a metafile while reading attributes from a physical device. Print preview is implemented in the framework in a similar fashion. You can also use the two device contexts in a similar way in your application-specific code.

There are times when you may need text-metric information from both the `m_hDC` and `m_hAttribDC` device contexts. The following pairs of functions provide this capability:

|Uses m_hAttribDC|Uses m_hDC|
|-----------------------|-----------------|
|[`GetTextExtent`](#gettextextent)|[`GetOutputTextExtent`](#getoutputtextextent)|
|[`GetTabbedTextExtent`](#gettabbedtextextent)|[`GetOutputTabbedTextExtent`](#getoutputtabbedtextextent)|
|[`GetTextMetrics`](#gettextmetrics)|[`GetOutputTextMetrics`](#getoutputtextmetrics)|
|[`GetCharWidth`](#getcharwidth)|[`GetOutputCharWidth`](#getoutputcharwidth)|

For more information on `CDC`, see [Device Contexts](../../mfc/device-contexts.md).

## Inheritance Hierarchy

[`CObject`](../../mfc/reference/cobject-class.md)

`CDC`

## Requirements

**Header:** `afxwin.h`

## <a name="abortdoc"></a> `CDC::AbortDoc`

Terminates the current print job and erases everything the application has written to the device since the last call to the [`StartDoc`](#startdoc) member function.

```
int AbortDoc();
```

### Return Value

A value greater than or equal to 0 if successful, or a negative value if an error has occurred. The following list shows common error values and their meanings:

- `SP_ERROR` General error.

- `SP_OUTOFDISK` Not enough disk space is currently available for spooling, and no more space will become available.

- `SP_OUTOFMEMORY` Not enough memory is available for spooling.

- `SP_USERABORT` User terminated the job through the Print Manager.

### Remarks

This member function replaces the `ABORTDOC` printer escape.

`AbortDoc` should be used to terminate the following:

- Printing operations that don't specify an abort function using [`SetAbortProc`](#setabortproc).

- Printing operations that have not yet reached their first `NEWFRAME` or `NEXTBAND` escape call.

If an application encounters a printing error or a canceled print operation, it must not attempt to terminate the operation by using either the [`EndDoc`](#enddoc) or `AbortDoc` member functions of class `CDC`. GDI automatically terminates the operation before returning the error value.

If the application displays a dialog box to allow the user to cancel the print operation, it must call `AbortDoc` before destroying the dialog box.

If Print Manager was used to start the print job, calling `AbortDoc` erases the entire spool job—the printer receives nothing. If Print Manager wasn't used to start the print job, the data may have been sent to the printer before `AbortDoc` was called. In this case, the printer driver would have reset the printer (when possible) and closed the print job.

### Example

  See the example for [`CDC::StartDoc`](#startdoc).

## <a name="abortpath"></a> `CDC::AbortPath`

Closes and discards any paths in the device context.

```
BOOL AbortPath();
```

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

If there's an open path bracket in the device context, the path bracket is closed and the path is discarded. If there's a closed path in the device context, the path is discarded.

## <a name="addmetafilecomment"></a> `CDC::AddMetaFileComment`

Copies the comment from a buffer into a specified enhanced-format metafile.

```
BOOL AddMetaFileComment(
    UINT nDataSize,
    const BYTE* pCommentData);
```

### Parameters

*`nDataSize`*\
Specifies the length of the comment buffer, in bytes.

*`pCommentData`*\
Points to the buffer that contains the comment.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

A comment may include any private information — for example, the source of the picture and the date it was created. A comment should begin with an application signature, followed by the data. Comments shouldn't contain position-specific data. Position-specific data specifies the location of a record, and it shouldn't be included because one metafile may be embedded within another metafile. This function can only be used with enhanced metafiles.

## <a name="alphablend"></a> `CDC::AlphaBlend`

Call this member function to display bitmaps that have transparent or semitransparent pixels.

```
BOOL AlphaBlend(
    int xDest,
    int yDest,
    int nDestWidth,
    int nDestHeight,
    CDC* pSrcDC,
    int xSrc,
    int ySrc,
    int nSrcWidth,
    int nSrcHeight,
    BLENDFUNCTION blend);
```

### Parameters

*`xDest`*\
Specifies the x-coordinate, in logical units, of the upper-left corner of the destination rectangle.

*`yDest`*\
Specifies the y-coordinate, in logical units, of the upper-left corner of the destination rectangle.

*`nDestWidth`*\
Specifies the width, in logical units, of the destination rectangle.

*`nDestHeight`*\
Specifies the height, in logical units, of the destination rectangle.

*`pSrcDC`*\
A pointer to the source device context.

*`xSrc`*\
Specifies the x-coordinate, in logical units, of the upper-left corner of the source rectangle.

*`ySrc`*\
Specifies the y-coordinate, in logical units, of the upper-left corner of the source rectangle.

*`nSrcWidth`*\
Specifies the width, in logical units, of the source rectangle.

*`nSrcHeight`*\
Specifies the height, in logical units, of the source rectangle.

*`blend`*\
Specifies a [`BLENDFUNCTION`](/windows/win32/api/wingdi/ns-wingdi-blendfunction) structure.

### Return Value

`TRUE` if successful; otherwise `FALSE`.

### Remarks

See [`AlphaBlend`](/windows/win32/api/wingdi/nf-wingdi-alphablend) in the Windows SDK for more information.

## <a name="anglearc"></a> `CDC::AngleArc`

Draws a line segment and an arc.

```
BOOL AngleArc(
    int x,
    int y,
    int nRadius,
    float fStartAngle,
    float fSweepAngle);
```

### Parameters

*`x`*\
Specifies the logical x-coordinate of the center of the circle.

*`y`*\
Specifies the logical y-coordinate of the center of the circle.

*`nRadius`*\
Specifies the radius of the circle in logical units. This value must be positive.

*`fStartAngle`*\
Specifies the starting angle in degrees relative to the x-axis.

*`fSweepAngle`*\
Specifies the sweep angle in degrees relative to the starting angle.

### Return Value

Nonzero if successful; otherwise 0.

### Remarks

The line segment is drawn from the current position to the beginning of the arc. The arc is drawn along the perimeter of a circle with the given radius and center. The length of the arc is defined by the given start and sweep angles.

`AngleArc` moves the current position to the ending point of the arc. The arc drawn by this function may appear to be elliptical, depending on the current transformation and mapping mode. Before drawing the arc, this function draws the line segment from the current position to the beginning of the arc. The arc is drawn by constructing an imaginary circle with the specified radius around the specified center point. The starting point of the arc is determined by measuring counterclockwise from the x-axis of the circle by the number of degrees in the start angle. The ending point is similarly located by measuring counterclockwise from the starting point by the number of degrees in the sweep angle.

If the sweep angle is greater than 360 degrees the arc is swept multiple times. This function draws lines by using the current pen. The figure isn't filled.

## <a name="arc"></a> `CDC::Arc`

Draws an elliptical arc.

```
BOOL Arc(
    int x1,
    int y1,
    int x2,
    int y2,
    int x3,
    int y3,
    int x4,
    int y4);

BOOL Arc(
    LPCRECT lpRect,
    POINT ptStart,
    POINT ptEnd);
```

### Parameters

*`x1`*\
Specifies the x-coordinate of the upper-left corner of the bounding rectangle (in logical units).

*`y1`*\
Specifies the y-coordinate of the upper-left corner of the bounding rectangle (in logical units).

*`x2`*\
Specifies the x-coordinate of the lower-right corner of the bounding rectangle (in logical units).

*`y2`*\
Specifies the y-coordinate of the lower-right corner of the bounding rectangle (in logical units).

*`x3`*\
Specifies the x-coordinate of the point that defines the arc's starting point (in logical units). This point doesn't have to lie exactly on the arc.

*`y3`*\
Specifies the y-coordinate of the point that defines the arc's starting point (in logical units). This point doesn't have to lie exactly on the arc.

*`x4`*\
Specifies the x-coordinate of the point that defines the arc's endpoint (in logical units). This point doesn't have to lie exactly on the arc.

*`y4`*\
Specifies the y-coordinate of the point that defines the arc's endpoint (in logical units). This point doesn't have to lie exactly on the arc.

*`lpRect`*\
Specifies the bounding rectangle (in logical units). You can pass either an `LPRECT` or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object for this parameter.

*`ptStart`*\
Specifies the x- and y-coordinates of the point that defines the arc's starting point (in logical units). This point doesn't have to lie exactly on the arc. You can pass either a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object for this parameter.

*`ptEnd`*\
Specifies the x- and y-coordinates of the point that defines the arc's ending point (in logical units). This point doesn't have to lie exactly on the arc. You can pass either a `POINT` structure or a `CPoint` object for this parameter.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The arc drawn by using the function is a segment of the ellipse defined by the specified bounding rectangle.

The actual starting point of the arc is the point at which a ray drawn from the center of the bounding rectangle through the specified starting point intersects the ellipse. The actual ending point of the arc is the point at which a ray drawn from the center of the bounding rectangle through the specified ending point intersects the ellipse. The arc is drawn in a counterclockwise direction. Since an arc isn't a closed figure, it isn't filled. Both the width and height of the rectangle must be greater than 2 units and less than 32,767 units.

### Example

[!code-cpp[NVC_MFCDocView#29](../../mfc/codesnippet/cpp/cdc-class_1.cpp)]

## <a name="arcto"></a> `CDC::ArcTo`

Draws an elliptical arc.

```
BOOL ArcTo(
    int x1,
    int y1,
    int x2,
    int y2,
    int x3,
    int y3,
    int x4,
    int y4);

BOOL ArcTo(
    LPCRECT lpRect,
    POINT ptStart,
    POINT ptEnd);
```

### Parameters

*`x1`*\
Specifies the x-coordinate of the upper-left corner of the bounding rectangle (in logical units).

*`y1`*\
Specifies the y-coordinate of the upper-left corner of the bounding rectangle (in logical units).

*`x2`*\
Specifies the x-coordinate of the lower-right corner of the bounding rectangle (in logical units).

*`y2`*\
Specifies the y-coordinate of the lower-right corner of the bounding rectangle (in logical units).

*`x3`*\
Specifies the x-coordinate of the point that defines the arc's starting point (in logical units). This point doesn't have to lie exactly on the arc.

*`y3`*\
Specifies the y-coordinate of the point that defines the arc's starting point (in logical units). This point doesn't have to lie exactly on the arc.

*`x4`*\
Specifies the x-coordinate of the point that defines the arc's endpoint (in logical units). This point doesn't have to lie exactly on the arc.

*`y4`*\
Specifies the y-coordinate of the point that defines the arc's endpoint (in logical units). This point doesn't have to lie exactly on the arc.

*`lpRect`*\
Specifies the bounding rectangle (in logical units). You can pass either a pointer to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) data structure or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object for this parameter.

*`ptStart`*\
Specifies the x- and y-coordinates of the point that defines the arc's starting point (in logical units). This point doesn't have to lie exactly on the arc. You can pass either a [`POINT`](/windows/win32/api/windef/ns-windef-point) data structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object for this parameter.

*`ptEnd`*\
Specifies the x- and y-coordinates of the point that defines the arc's ending point (in logical units). This point doesn't have to lie exactly on the arc. You can pass either a `POINT` data structure or a `CPoint` object for this parameter.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

This function is similar to `CDC::Arc`, except that the current position is updated. The points ( *`x1`*, *`y1`*) and ( *`x2`*, *`y2`*) specify the bounding rectangle. An ellipse formed by the given bounding rectangle defines the curve of the arc. The arc extends counterclockwise (the default arc direction) from the point where it intersects the radial line from the center of the bounding rectangle to ( *`x3`*, *`y3`*). The arc ends where it intersects the radial line from the center of the bounding rectangle to ( *`x4`*, *`y4`*). If the starting point and ending point are the same, a complete ellipse is drawn.

A line is drawn from the current position to the starting point of the arc. If no error occurs, the current position is set to the ending point of the arc. The arc is drawn using the current pen; it isn't filled.

## <a name="attach"></a> `CDC::Attach`

Use this member function to attach an *`hDC`* to the `CDC` object.

```
BOOL Attach(HDC hDC);
```

### Parameters

*`hDC`*\
A Windows device context.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The *`hDC`* is stored in both `m_hDC`, the output device context, and in `m_hAttribDC`, the attribute device context.

## <a name="beginpath"></a> `CDC::BeginPath`

Opens a path bracket in the device context.

```
BOOL BeginPath();
```

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

After a path bracket is open, an application can begin calling GDI drawing functions to define the points that lie in the path. An application can close an open path bracket by calling the `EndPath` member function. When an application calls `BeginPath`, any previous paths are discarded.

See [`BeginPath`](/windows/win32/api/wingdi/nf-wingdi-beginpath) in the Windows SDK for a list of the drawing functions that define points in a path.

### Example

[!code-cpp[NVC_MFCDocView#30](../../mfc/codesnippet/cpp/cdc-class_2.cpp)]

## <a name="bitblt"></a> `CDC::BitBlt`

Copies a bitmap from the source device context to this current device context.

```
BOOL BitBlt(
    int x,
    int y,
    int nWidth,
    int nHeight,
    CDC* pSrcDC,
    int xSrc,
    int ySrc,
    DWORD dwRop);
```

### Parameters

*`x`*\
Specifies the logical x-coordinate of the upper-left corner of the destination rectangle.

*`y`*\
Specifies the logical y-coordinate of the upper-left corner of the destination rectangle.

*`nWidth`*\
Specifies the width (in logical units) of the destination rectangle and source bitmap.

*`nHeight`*\
Specifies the height (in logical units) of the destination rectangle and source bitmap.

*`pSrcDC`*\
Pointer to a `CDC` object that identifies the device context from which the bitmap will be copied. It must be `NULL` if *`dwRop`* specifies a raster operation that doesn't include a source.

*`xSrc`*\
Specifies the logical x-coordinate of the upper-left corner of the source bitmap.

*`ySrc`*\
Specifies the logical y-coordinate of the upper-left corner of the source bitmap.

*`dwRop`*\
Specifies the raster operation to be performed. Raster-operation codes define how the GDI combines colors in output operations that involve a current brush, a possible source bitmap, and a destination bitmap. See [`BitBlt`](/windows/win32/api/wingdi/nf-wingdi-bitblt) in the Windows SDK for a list of the raster-operation codes for *`dwRop`* and their descriptions

For a complete list of raster-operation codes, see [About Raster Operation Codes](/windows/win32/gdi/raster-operation-codes) in the Windows SDK.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The application can align the windows or client areas on byte boundaries to ensure that the `BitBlt` operations occur on byte-aligned rectangles. (Set the `CS_BYTEALIGNWINDOW` or `CS_BYTEALIGNCLIENT` flags when you register the window classes.)

`BitBlt` operations on byte-aligned rectangles are considerably faster than `BitBlt` operations on rectangles that aren't byte aligned. If you want to specify class styles such as byte-alignment for your own device context, you'll have to register a window class rather than relying on the Microsoft Foundation classes to do it for you. Use the global function [`AfxRegisterWndClass`](../../mfc/reference/application-information-and-management.md#afxregisterwndclass).

GDI transforms *`nWidth`* and *`nHeight`*, once by using the destination device context, and once by using the source device context. If the resulting extents don't match, GDI uses the Windows `StretchBlt` function to compress or stretch the source bitmap as necessary.

If destination, source, and pattern bitmaps don't have the same color format, the `BitBlt` function converts the source and pattern bitmaps to match the destination. The foreground and background colors of the destination bitmap are used in the conversion.

When the `BitBlt` function converts a monochrome bitmap to color, it sets white bits (1) to the background color and black bits (0) to the foreground color. The foreground and background colors of the destination device context are used. To convert color to monochrome, `BitBlt` sets pixels that match the background color to white and sets all other pixels to black. `BitBlt` uses the foreground and background colors of the color device context to convert from color to monochrome.

Not all device contexts support `BitBlt`. To check whether a given device context does support `BitBlt`, use the `GetDeviceCaps` member function and specify the RASTERCAPS index.

### Example

  See the example for [`CDC::CreateCompatibleDC`](#createcompatibledc).

## <a name="cdc"></a> `CDC::CDC`

Constructs a `CDC` object.

```
CDC();
```

## <a name="chord"></a> `CDC::Chord`

Draws a chord (a closed figure bounded by the intersection of an ellipse and a line segment).

```
BOOL Chord(
    int x1,
    int y1,
    int x2,
    int y2,
    int x3,
    int y3,
    int x4,
    int y4);

BOOL Chord(
    LPCRECT lpRect,
    POINT ptStart,
    POINT ptEnd);
```

### Parameters

*`x1`*\
Specifies the x-coordinate of the upper-left corner of the chord's bounding rectangle (in logical units).

*`y1`*\
Specifies the y-coordinate of the upper-left corner of the chord's bounding rectangle (in logical units).

*`x2`*\
Specifies the x-coordinate of the lower-right corner of the chord's bounding rectangle (in logical units).

*`y2`*\
Specifies the y-coordinate of the lower-right corner of the chord's bounding rectangle (in logical units).

*`x3`*\
Specifies the x-coordinate of the point that defines the chord's starting point (in logical units).

*`y3`*\
Specifies the y-coordinate of the point that defines the chord's starting point (in logical units).

*`x4`*\
Specifies the x-coordinate of the point that defines the chord's endpoint (in logical units).

*`y4`*\
Specifies the y-coordinate of the point that defines the chord's endpoint (in logical units).

*`lpRect`*\
Specifies the bounding rectangle (in logical units). You can pass either a `LPRECT` or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object for this parameter.

*`ptStart`*\
Specifies the x- and y-coordinates of the point that defines the chord's starting point (in logical units). This point doesn't have to lie exactly on the chord. You can pass either a `POINT` structure or a `CPoint` object for this parameter.

*`ptEnd`*\
Specifies the x- and y-coordinates of the point that defines the chord's ending point (in logical units). This point doesn't have to lie exactly on the chord. You can pass either a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object for this parameter.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The ( *`x1`*, *`y1`*) and ( *`x2`*, *`y2`*) parameters specify the upper-left and lower-right corners, respectively, of a rectangle bounding the ellipse that is part of the chord. The ( *`x3`*, *`y3`*) and ( *`x4`*, *`y4`*) parameters specify the endpoints of a line that intersects the ellipse. The chord is drawn by using the selected pen and filled by using the selected brush.

The figure drawn by the `Chord` function extends up to, but doesn't include the right and bottom coordinates. This means that the height of the figure is *`y2`* - *`y1`* and the width of the figure is *`x2`* - *`x1`*.

### Example

[!code-cpp[NVC_MFCDocView#31](../../mfc/codesnippet/cpp/cdc-class_3.cpp)]

## <a name="closefigure"></a> `CDC::CloseFigure`

Closes an open figure in a path.

```
BOOL CloseFigure();
```

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The function closes the figure by drawing a line from the current position to the first point of the figure (usually, the point specified by the most recent call to the `MoveTo` member function) and connects the lines by using the line join style. If a figure is closed by using the `LineTo` member function instead of `CloseFigure`, end caps are used to create the corner instead of a join. `CloseFigure` should only be called if there's an open path bracket in the device context.

A figure in a path is open unless it's explicitly closed by using this function. (A figure can be open even if the current point and the starting point of the figure are the same.) Any line or curve added to the path after `CloseFigure` starts a new figure.

## <a name="createcompatibledc"></a> `CDC::CreateCompatibleDC`

Creates a memory device context that is compatible with the device specified by *`pDC`*.

```
BOOL CreateCompatibleDC(CDC* pDC);
```

### Parameters

*`pDC`*\
A pointer to a device context. If *`pDC`* is `NULL`, the function creates a memory device context that is compatible with the system display.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

A memory device context is a block of memory that represents a display surface. It can be used to prepare images in memory before copying them to the actual device surface of the compatible device.

When a memory device context is created, GDI automatically selects a 1-by-1 monochrome stock bitmap for it. GDI output functions can be used with a memory device context only if a bitmap has been created and selected into that context.

This function can only be used to create compatible device contexts for devices that support raster operations. See the [`CDC::BitBlt`](#bitblt) member function for information regarding bit-block transfers between device contexts. To determine whether a device context supports raster operations, see the `RC_BITBLT` raster capability in the member function `CDC::GetDeviceCaps`.

### Example

[!code-cpp[NVC_MFCDocView#32](../../mfc/codesnippet/cpp/cdc-class_4.cpp)]

## <a name="createdc"></a> `CDC::CreateDC`

Creates a device context for the specified device.

```
BOOL CreateDC(
    LPCTSTR lpszDriverName,
    LPCTSTR lpszDeviceName,
    LPCTSTR lpszOutput,
    const void* lpInitData);
```

### Parameters

*`lpszDriverName`*\
Points to a null-terminated string that specifies the filename (without extension) of the device driver (for example, "`EPSON`"). You can also pass a `CString` object for this parameter.

*`lpszDeviceName`*\
Points to a null-terminated string that specifies the name of the specific device to be supported (for example, "`EPSON FX-80`"). The *`lpszDeviceName`* parameter is used if the module supports more than one device. You can also pass a `CString` object for this parameter.

*`lpszOutput`*\
Points to a null-terminated string that specifies the file or device name for the physical output medium (file or output port). You can also pass a `CString` object for this parameter.

*`lpInitData`*\
Points to a `DEVMODE` structure containing device-specific initialization data for the device driver. The Windows `DocumentProperties` function retrieves this structure filled in for a given device. The *`lpInitData`* parameter must be `NULL` if the device driver is to use the default initialization (if any) specified by the user through the Control Panel.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The `PRINT.H` header file is required if the [`DEVMODE`](/windows/win32/api/wingdi/ns-wingdi-devmodea) structure is used.

Device names follow these conventions: an ending colon (:) is recommended, but optional. Windows strips the terminating colon so that a device name ending with a colon is mapped to the same port as the same name without a colon. The driver and port names must not contain leading or trailing spaces. GDI output functions cannot be used with information contexts.

## <a name="createic"></a> `CDC::CreateIC`

Creates an information context for the specified device.

```
BOOL CreateIC(
    LPCTSTR lpszDriverName,
    LPCTSTR lpszDeviceName,
    LPCTSTR lpszOutput,
    const void* lpInitData);
```

### Parameters

*`lpszDriverName`*\
Points to a null-terminated string that specifies the filename (without extension) of the device driver (for example, "`EPSON`"). You can pass a `CString` object for this parameter.

*`lpszDeviceName`*\
Points to a null-terminated string that specifies the name of the specific device to be supported (for example, "`EPSON FX-80`"). The *`lpszDeviceName`* parameter is used if the module supports more than one device. You can pass a `CString` object for this parameter.

*`lpszOutput`*\
Points to a null-terminated string that specifies the file or device name for the physical output medium (file or port). You can pass a `CString` object for this parameter.

*`lpInitData`*\
Points to device-specific initialization data for the device driver. The *`lpInitData`* parameter must be `NULL` if the device driver is to use the default initialization (if any) specified by the user through the Control Panel. See `CreateDC` for the data format for device-specific initialization.

### Return Value

Nonzero if successful; otherwise 0.

### Remarks

The information context provides a fast way to get information about the device without creating a device context.

Device names follow these conventions: an ending colon (:) is recommended, but optional. Windows strips the terminating colon so that a device name ending with a colon is mapped to the same port as the same name without a colon. The driver and port names must not contain leading or trailing spaces. GDI output functions cannot be used with information contexts.

## <a name="deletedc"></a> `CDC::DeleteDC`

In general, don't call this function; the destructor will do it for you.

```
BOOL DeleteDC();
```

### Return Value

Nonzero if the function completed successfully; otherwise 0.

### Remarks

The `DeleteDC` member function deletes the Windows device contexts that are associated with `m_hDC` in the current `CDC` object. If this `CDC` object is the last active device context for a given device, all storage and system resources used by the device are released.

An application shouldn't call `DeleteDC` if objects have been selected into the device context. Objects must first be selected out of the device context before it's deleted.

An application must not delete a device context whose handle was obtained by calling [`CWnd::GetDC`](../../mfc/reference/cwnd-class.md#getdc). Instead, it must call [`CWnd::ReleaseDC`](../../mfc/reference/cwnd-class.md#releasedc) to free the device context. The [`CClientDC`](../../mfc/reference/cclientdc-class.md) and [`CWindowDC`](../../mfc/reference/cwindowdc-class.md) classes are provided to wrap this functionality.

The `DeleteDC` function is generally used to delete device contexts created with [`CreateDC`](#createdc), [`CreateIC`](#createic), or [`CreateCompatibleDC`](#createcompatibledc).

### Example

  See the example for [`CPrintDialog::GetPrinterDC`](../../mfc/reference/cprintdialog-class.md#getprinterdc).

## <a name="deletetempmap"></a> `CDC::DeleteTempMap`

Called automatically by the `CWinApp` idle-time handler, `DeleteTempMap` deletes any temporary `CDC` objects created by `FromHandle`, but doesn't destroy the device context handles (`hDC`s) temporarily associated with the `CDC` objects.

```
static void PASCAL DeleteTempMap();
```

## <a name="detach"></a> `CDC::Detach`

Call this function to detach `m_hDC` (the output device context) from the `CDC` object and set both `m_hDC` and `m_hAttribDC` to `NULL`.

```
HDC Detach();
```

### Return Value

A Windows device context.

## <a name="dptohimetric"></a> `CDC::DPtoHIMETRIC`

Use this function when you give `HIMETRIC` sizes to OLE, converting pixels to `HIMETRIC`.

```cpp
void DPtoHIMETRIC(LPSIZE lpSize) const;
```

### Parameters

*`lpSize`*\
Points to a [SIZE](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object.

### Remarks

If the mapping mode of the device context object is `MM_LOENGLISH`, `MM_HIENGLISH`, `MM_LOMETRIC`, or `MM_HIMETRIC`, then the conversion is based on the number of pixels in the physical inch. If the mapping mode is one of the other non-constrained modes (for example, `MM_TEXT`), then the conversion is based on the number of pixels in the logical inch.

## <a name="dptolp"></a> `CDC::DPtoLP`

Converts device units into logical units.

```cpp
void DPtoLP(
    LPPOINT lpPoints,
    int nCount = 1) const;

void DPtoLP(LPRECT lpRect) const;
void DPtoLP(LPSIZE lpSize) const;
```

### Parameters

*`lpPoints`*\
Points to an array of [`POINT`](/windows/win32/api/windef/ns-windef-point) structures or [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) objects.

*`nCount`*\
The number of points in the array.

*`lpRect`*\
Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object. This parameter is used for the simple case of converting one rectangle from device points to logical points.

*`lpSize`*\
Points to a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object.

### Remarks

The function maps the coordinates of each point, or dimension of a size, from the device coordinate system into GDI's logical coordinate system. The conversion depends on the current mapping mode and the settings of the origins and extents for the device's window and viewport.

## <a name="draw3drect"></a> `CDC::Draw3dRect`

Call this member function to draw a three-dimensional rectangle.

```cpp
void Draw3dRect(
    LPCRECT lpRect,
    COLORREF clrTopLeft,
    COLORREF clrBottomRight);

void Draw3dRect(
    int x,
    int y,
    int cx,
    int cy,
    COLORREF clrTopLeft,
    COLORREF clrBottomRight);
```

### Parameters

*`lpRect`*\
Specifies the bounding rectangle (in logical units). You can pass either a pointer to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object for this parameter.

*`clrTopLeft`*\
Specifies the color of the top and left sides of the three-dimensional rectangle.

*`clrBottomRight`*\
Specifies the color of the bottom and right sides of the three-dimensional rectangle.

*`x`*\
Specifies the logical x-coordinate of the upper-left corner of the three-dimensional rectangle.

*`y`*\
Specifies the logical y-coordinate of the upper-left corner of the three-dimensional rectangle.

*`cx`*\
Specifies the width of the three-dimensional rectangle.

*`cy`*\
Specifies the height of the three-dimensional rectangle.

### Remarks

The rectangle will be drawn with the top and left sides in the color specified by *`clrTopLeft`* and the bottom and right sides in the color specified by *`clrBottomRight`*.

### Example

[!code-cpp[NVC_MFCDocView#33](../../mfc/codesnippet/cpp/cdc-class_5.cpp)]

## <a name="drawdragrect"></a> `CDC::DrawDragRect`

Call this member function repeatedly to redraw a drag rectangle.

```cpp
void DrawDragRect(
    LPCRECT lpRect,
    SIZE size,
    LPCRECT lpRectLast,
    SIZE sizeLast,
    CBrush* pBrush = NULL,
    CBrush* pBrushLast = NULL);
```

### Parameters

*`lpRect`*\
Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that specifies the logical coordinates of a rectangle — in this case, the end position of the rectangle being redrawn.

*`size`*\
Specifies the displacement from the top-left corner of the outer border to the top-left corner of the inner border (that is, the thickness of the border) of a rectangle.

*`lpRectLast`*\
Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that specifies the logical coordinates of the position of a rectangle — in this case, the original position of the rectangle being redrawn.

*`sizeLast`*\
Specifies the displacement from the top-left corner of the outer border to the top-left corner of the inner border (that is, the thickness of the border) of the original rectangle being redrawn.

*`pBrush`*\
Pointer to a brush object. Set to `NULL` to use the default halftone brush.

*`pBrushLast`*\
Pointer to the last brush object used. Set to `NULL` to use the default halftone brush.

### Remarks

Call it in a loop as you sample mouse position, in order to give visual feedback. When you call `DrawDragRect`, the previous rectangle is erased and a new one is drawn. For example, as the user drags a rectangle across the screen, `DrawDragRect` will erase the original rectangle and redraw a new one in its new position. By default, `DrawDragRect` draws the rectangle by using a halftone brush to eliminate flicker and to create the appearance of a smoothly moving rectangle.

The first time you call `DrawDragRect`, the *`lpRectLast`* parameter should be `NULL`.

## <a name="drawedge"></a> `CDC::DrawEdge`

Call this member function to draw the edges of a rectangle of the specified type and style.

```
BOOL DrawEdge(
    LPRECT lpRect,
    UINT nEdge,
    UINT nFlags);
```

### Parameters

*`lpRect`*\
A pointer to a `RECT` structure that contains the logical coordinates of the rectangle.

*`nEdge`*\
Specifies the type of inner and outer edge to draw. This parameter must be a combination of one inner-border flag and one outer-border flag. See [`DrawEdge`](/windows/win32/api/winuser/nf-winuser-drawedge) in the Windows SDK for a table of the parameter's types.

*`nFlags`*\
The flags that specify the type of border to be drawn. See `DrawEdge` in the Windows SDK for a table of the parameter's values. For diagonal lines, the `BF_RECT` flags specify the end point of the vector bounded by the rectangle parameter.

### Return Value

Nonzero if successful; otherwise 0.

## <a name="drawescape"></a> `CDC::DrawEscape`

Accesses drawing capabilities of a video display that aren't directly available through the graphics device interface (GDI).

```
int DrawEscape(
    int nEscape,
    int nInputSize,
    LPCSTR lpszInputData);
```

### Parameters

*`nEscape`*\
Specifies the escape function to be performed.

*`nInputSize`*\
Specifies the number of bytes of data pointed to by the *`lpszInputData`* parameter.

*`lpszInputData`*\
Points to the input structure required for the specified escape.

### Return Value

Specifies the outcome of the function. Greater than zero if successful, except for the `QUERYESCSUPPORT` draw escape, which checks for implementation only; or zero if the escape isn't implemented; or less than zero if an error occurred.

### Remarks

When an application calls `DrawEscape`, the data identified by *`nInputSize`* and *`lpszInputData`* is passed directly to the specified display driver.

## <a name="drawfocusrect"></a> `CDC::DrawFocusRect`

Draws a rectangle in the style used to indicate that the rectangle has the focus.

```cpp
void DrawFocusRect(LPCRECT lpRect);
```

### Parameters

*`lpRect`*\
Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that specifies the logical coordinates of the rectangle to be drawn.

### Remarks

Since this is a Boolean **XOR** (`^`) function, calling this function a second time with the same rectangle removes the rectangle from the display. The rectangle drawn by this function cannot be scrolled. To scroll an area containing a rectangle drawn by this function, first call `DrawFocusRect` to remove the rectangle from the display, then scroll the area, and then call `DrawFocusRect` again to draw the rectangle in the new position.

> [!CAUTION]
> `DrawFocusRect` works only in `MM_TEXT` mode. In other modes, this function doesn't draw the focus rectangle correctly, but it doesn't return error values.

## <a name="drawframecontrol"></a> `CDC::DrawFrameControl`

Call this member function to draw a frame control of the specified type and style.

```
BOOL DrawFrameControl(
    LPRECT lpRect,
    UINT nType,
    UINT nState);
```

### Parameters

*`lpRect`*\
A pointer to a `RECT` structure that contains the logical coordinates of the rectangle.

*`nType`*\
Specifies the type of frame control to draw. See the *`uType`* parameter in [`DrawFrameControl`](/windows/win32/api/winuser/nf-winuser-drawframecontrol) in the Windows SDK for a list of this parameter's possible values.

*`nState`*\
Specifies the initial state of the frame control. Can be one or more of the values described for the *`uState`* parameter in `DrawFrameControl` in the Windows SDK. Use the *`nState`* value `DFCS_ADJUSTRECT` to adjust the bounding rectangle to exclude the surrounding edge of the push button.

### Return Value

Nonzero if successful; otherwise 0.

### Remarks

In several cases, *`nState`* depends on the *`nType`* parameter. The following list shows the relationship between the four *`nType`* values and *`nState`*:

- `DFC_BUTTON`

  - `DFCS_BUTTON3STATE` Three-state button

  - `DFCS_BUTTONCHECK` Check box

  - `DFCS_BUTTONPUSH` Push button

  - `DFCS_BUTTONRADIO` Radio button

  - `DFCS_BUTTONRADIOIMAGE` Image for radio button (nonsquare needs image)

  - `DFCS_BUTTONRADIOMASK` Mask for radio button (nonsquare needs mask)

- `DFC_CAPTION`

  - `DFCS_CAPTIONCLOSE` Close button

  - `DFCS_CAPTIONHELP` Help button

  - `DFCS_CAPTIONMAX` Maximize button

  - `DFCS_CAPTIONMIN` Minimize button

  - `DFCS_CAPTIONRESTORE` Restore button

- `DFC_MENU`

  - `DFCS_MENUARROW` Submenu arrow

  - `DFCS_MENUBULLET` Bullet

  - `DFCS_MENUCHECK` Check mark

- `DFC_SCROLL`

  - `DFCS_SCROLLCOMBOBOX` Combo box scroll bar

  - `DFCS_SCROLLDOWN` Down arrow of scroll bar

  - `DFCS_SCROLLLEFT` Left arrow of scroll bar

  - `DFCS_SCROLLRIGHT` Right arrow of scroll bar

  - `DFCS_SCROLLSIZEGRIP` Size grip in bottom-right corner of window

  - `DFCS_SCROLLUP` Up arrow of scroll bar

### Example

This code draws the size gripper in the bottom-right corner of your window. It's appropriate for the `OnPaint` handler of a dialog box, which has no styles and normally doesn't contain other controls (like a status bar) that may give it a size gripper.

[!code-cpp[NVC_MFCDocView#34](../../mfc/codesnippet/cpp/cdc-class_6.cpp)]

## <a name="drawicon"></a> `CDC::DrawIcon`

Draws an icon on the device represented by the current `CDC` object.

```
BOOL DrawIcon(
    int x,
    int y,
    HICON hIcon);

BOOL DrawIcon(
    POINT point,
    HICON hIcon);
```

### Parameters

*`x`*\
Specifies the logical x-coordinate of the upper-left corner of the icon.

*`y`*\
Specifies the logical y-coordinate of the upper-left corner of the icon.

*`hIcon`*\
Identifies the handle of the icon to be drawn.

*`point`*\
Specifies the logical x- and y-coordinates of the upper-left corner of the icon. You can pass a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object for this parameter.

### Return Value

Nonzero if the function completed successfully; otherwise 0.

### Remarks

The function places the icon's upper-left corner at the location specified by *`x`* and *`y`*. The location is subject to the current mapping mode of the device context.

The icon resource must have been previously loaded by using the functions `CWinApp::LoadIcon`, `CWinApp::LoadStandardIcon`, or `CWinApp::LoadOEMIcon`. The `MM_TEXT` mapping mode must be selected prior to using this function.

### Example

  See the example for [`CWnd::IsIconic`](../../mfc/reference/cwnd-class.md#isiconic).

## <a name="drawstate"></a> `CDC::DrawState`

Call this member function to display an image and apply a visual effect to indicate a state, such as a disabled or default state.

> [!NOTE]
> For all *`nFlag`* states except `DSS_NORMAL`, the image is converted to monochrome before the visual effect is applied.

```
BOOL DrawState(
    CPoint pt,
    CSize size,
    HBITMAP hBitmap,
    UINT nFlags,
    HBRUSH hBrush = NULL);

BOOL DrawState(
    CPoint pt,
    CSize size,
    CBitmap* pBitmap,
    UINT nFlags,
    CBrush* pBrush = NULL);

BOOL DrawState(
    CPoint pt,
    CSize size,
    HICON hIcon,
    UINT nFlags,
    HBRUSH hBrush = NULL);

BOOL DrawState(
    CPoint pt,
    CSize size,
    HICON hIcon,
    UINT nFlags,
    CBrush* pBrush = NULL);

BOOL DrawState(
    CPoint pt,
    CSize size,
    LPCTSTR lpszText,
    UINT nFlags,
    BOOL bPrefixText = TRUE,
    int nTextLen = 0,
    HBRUSH hBrush = NULL);

BOOL DrawState(
    CPoint pt,
    CSize size,
    LPCTSTR lpszText,
    UINT nFlags,
    BOOL bPrefixText = TRUE,
    int nTextLen = 0,
    CBrush* pBrush = NULL);

BOOL DrawState(
    CPoint pt,
    CSize size,
    DRAWSTATEPROC lpDrawProc,
    LPARAM lData,
    UINT nFlags,
    HBRUSH hBrush = NULL);

BOOL DrawState(
    CPoint pt,
    CSize size,
    DRAWSTATEPROC lpDrawProc,
    LPARAM lData,
    UINT nFlags,
    CBrush* pBrush = NULL);
```

### Parameters

*`pt`*\
Specifies the location of the image.

*`size`*\
Specifies the size of the image.

*`hBitmap`*\
A handle to a bitmap.

*`nFlags`*\
Flags that specify the image type and state. See [`DrawState`](/windows/win32/api/winuser/nf-winuser-drawstatew) in the Windows SDK for the possible *nFlags* types and states.

*`hBrush`*\
A handle to a brush.

*`pBitmap`*\
A pointer to a `CBitmap` object.

*`pBrush`*\
A pointer to a `CBrush` object.

*`hIcon`*\
A handle to an icon.

*`lpszText`*\
A pointer to text.

*`bPrefixText`*\
Text that may contain an accelerator mnemonic. The *`lData`* parameter specifies the address of the string, and the *`nTextLen`* parameter specifies the length. If *`nTextLen`* is 0, the string is assumed to be null-terminated.

*`nTextLen`*\
Length of the text string pointed to by *`lpszText`*. If *`nTextLen`* is 0, the string is assumed to be null-terminated.

*`lpDrawProc`*\
A pointer to a callback function used to render an image. This parameter is required if the image type in *`nFlags`* is `DST_COMPLEX`. It's optional and can be `NULL` if the image type is `DST_TEXT`. For all other image types, this parameter is ignored. For more information about the callback function, see the [`DrawStateProc`](/windows/win32/api/winuser/nc-winuser-drawstateproc) function in the Windows SDK.

*`lData`*\
Specifies information about the image. The meaning of this parameter depends on the image type.

### Return Value

Nonzero if successful; otherwise 0.

## <a name="drawtext"></a> `CDC::DrawText`

Call this member function to format text in the given rectangle. To specify more formatting options, use [`CDC::DrawTextEx`](#drawtextex).

```
virtual int DrawText(
    LPCTSTR lpszString,
    int nCount,
    LPRECT lpRect,
    UINT nFormat);

int DrawText(
    const CString& str,
    LPRECT lpRect,
    UINT nFormat);
```

### Parameters

*`lpszString`*\
Points to the string to be drawn. If *`nCount`* is -1, the string must be null-terminated.

*`nCount`*\
Specifies the number of chars in the string. If *`nCount`* is -1, then *`lpszString`* is assumed to be a long pointer to a null-terminated string and `DrawText` computes the character count automatically.

*`lpRect`*\
Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that contains the rectangle (in logical coordinates) in which the text is to be formatted.

*`str`*\
A [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object that contains the specified characters to be drawn.

*`nFormat`*\
Specifies the method of formatting the text. It can be any combination of the values described for the *`uFormat`* parameter in [`DrawText`](/windows/win32/api/winuser/nf-winuser-drawtext) in the Windows SDK. (combine using the bitwise OR operator):

> [!NOTE]
> Some *`uFormat`* flag combinations can cause the passed string to be modified. Using `DT_MODIFYSTRING` with either `DT_END_ELLIPSIS` or `DT_PATH_ELLIPSIS` may cause the string to be modified, causing an assertion in the `CString` override. The values `DT_CALCRECT`, `DT_EXTERNALLEADING`, `DT_INTERNAL`, `DT_NOCLIP`, and `DT_NOPREFIX` cannot be used with the `DT_TABSTOP` value.

### Return Value

The height of the text if the function is successful.

### Remarks

It formats text by expanding tabs into appropriate spaces, aligning text to the left, right, or center of the given rectangle, and breaking text into lines that fit within the given rectangle. The type of formatting is specified by *`nFormat`*.

This member function uses the device context's selected font, text color, and background color to draw the text. Unless the `DT_NOCLIP` format is used, `DrawText` clips the text so that the text doesn't appear outside the given rectangle. All formatting is assumed to have multiple lines unless the `DT_SINGLELINE` format is given.

If the selected font is too large for the specified rectangle, the `DrawText` member function doesn't attempt to substitute a smaller font.

If the `DT_CALCRECT` flag is specified, the rectangle specified by *`lpRect`* will be updated to reflect the width and height needed to draw the text.

If the `TA_UPDATECP` text-alignment flag has been set (see [`CDC::SetTextAlign`](#settextalign)), `DrawText` will display text starting at the current position, rather than at the left of the given rectangle. `DrawText` won't wrap text when the `TA_UPDATECP` flag has been set (that is, the `DT_WORDBREAK` flag will have no effect).

The text color may be set by [`CDC::SetTextColor`](#settextcolor).

## <a name="drawtextex"></a> `CDC::DrawTextEx`

Formats text in the given rectangle.

```
virtual int DrawTextEx(
    LPTSTR lpszString,
    int nCount,
    LPRECT lpRect,
    UINT nFormat,
    LPDRAWTEXTPARAMS lpDTParams);

int DrawTextEx(
    const CString& str,
    LPRECT lpRect,
    UINT nFormat,
    LPDRAWTEXTPARAMS lpDTParams);
```

### Parameters

*`lpszString`*\
Points to the string to be drawn. If *`nCount`* is -1, the string must be null terminated.

*`nCount`*\
Specifies the number of chars in the string. If *`nCount`* is -1, then *`lpszString`* is assumed to be a long pointer to a null-terminated string and `DrawText` computes the character count automatically.

*`lpRect`*\
Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that contains the rectangle (in logical coordinates) in which the text is to be formatted.

*`str`*\
A [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object that contains the specified characters to be drawn.

*`nFormat`*\
Specifies the method of formatting the text. It can be any combination of the values described for the *`uFormat`* parameter in [`DrawText`](/windows/win32/api/winuser/nf-winuser-drawtext) in the Windows SDK. (Combine using the bitwise **OR** operator):

> [!NOTE]
> Some *`uFormat`* flag combinations can cause the passed string to be modified. Using `DT_MODIFYSTRING` with either `DT_END_ELLIPSIS` or `DT_PATH_ELLIPSIS` may cause the string to be modified, causing an assertion in the `CString` override. The values `DT_CALCRECT`, `DT_EXTERNALLEADING`, `DT_INTERNAL`, `DT_NOCLIP`, and `DT_NOPREFIX` cannot be used with the `DT_TABSTOP` value.

*`lpDTParams`*\
Pointer to a [`DRAWTEXTPARAMS`](/windows/win32/api/winuser/ns-winuser-drawtextparams) structure that specifies more formatting options. This parameter can be `NULL`.

### Remarks

It formats text by expanding tabs into appropriate spaces, aligning text to the left, right, or center of the given rectangle, and breaking text into lines that fit within the given rectangle. The type of formatting is specified by *`nFormat`* and *`lpDTParams`*. For more information, see [`CDC::DrawText`](#drawtext) and [`DrawTextEx`](/windows/win32/api/winuser/nf-winuser-drawtextexw) in the Windows SDK.

The text color may be set by [`CDC::SetTextColor`](#settextcolor).

## <a name="ellipse"></a> `CDC::Ellipse`

Draws an ellipse.

```
BOOL Ellipse(
    int x1,
    int y1,
    int x2,
    int y2);

BOOL Ellipse(LPCRECT lpRect);
```

### Parameters

*`x1`*\
Specifies the logical x-coordinate of the upper-left corner of the ellipse's bounding rectangle.

*`y1`*\
Specifies the logical y-coordinate of the upper-left corner of the ellipse's bounding rectangle.

*`x2`*\
Specifies the logical x-coordinate of the lower-right corner of the ellipse's bounding rectangle.

*`y2`*\
Specifies the logical y-coordinate of the lower-right corner of the ellipse's bounding rectangle.

*`lpRect`*\
Specifies the ellipse's bounding rectangle. You can also pass a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object for this parameter.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The center of the ellipse is the center of the bounding rectangle specified by *`x1`*, *`y1`*, *`x2`*, and *`y2`*, or *`lpRect`*. The ellipse is drawn with the current pen, and its interior is filled with the current brush.

The figure drawn by this function extends up to, but doesn't include, the right and bottom coordinates. This means that the height of the figure is *`y2`* - *`y1`* and the width of the figure is *`x2`* - *`x1`*.

If either the width or the height of the bounding rectangle is 0, no ellipse is drawn.

## <a name="enddoc"></a> `CDC::EndDoc`

Ends a print job started by a call to the [`StartDoc`](#startdoc) member function.

```
int EndDoc();
```

### Return Value

Greater than or equal to 0 if the function is successful, or a negative value if an error occurred.

### Remarks

This member function replaces the `ENDDOC` printer escape, and should be called immediately after finishing a successful print job.

If an application encounters a printing error or a canceled print operation, it must not attempt to terminate the operation by using either `EndDoc` or [`AbortDoc`](#abortdoc). GDI automatically terminates the operation before returning the error value.

This function shouldn't be used inside metafiles.

### Example

  See the example for [`CDC::StartDoc`](#startdoc).

## <a name="endpage"></a> `CDC::EndPage`

Informs the device that the application has finished writing to a page.

```
int EndPage();
```

### Return Value

Greater than or equal to 0 if the function is successful, or a negative value if an error occurred.

### Remarks

This member function is typically used to direct the device driver to advance to a new page.

This member function replaces the `NEWFRAME` printer escape. Unlike `NEWFRAME`, this function is always called after printing a page.

### Example

  See the example for [`CDC::StartDoc`](#startdoc).

## <a name="endpath"></a> `CDC::EndPath`

Closes a path bracket and selects the path defined by the bracket into the device context.

```
BOOL EndPath();
```

### Return Value

Nonzero if the function is successful; otherwise 0.

### Example

  See the example for [`CDC::BeginPath`](#beginpath).

## <a name="enumobjects"></a> `CDC::EnumObjects`

Enumerates the pens and brushes available in a device context.

```
int EnumObjects(
    int nObjectType,
    int (CALLBACK* lpfn)(
    LPVOID,
    LPARAM),
    LPARAM lpData);
```

### Parameters

*`nObjectType`*\
Specifies the object type. It can have the values `OBJ_BRUSH` or `OBJ_PEN`.

*`lpfn`*\
Is the procedure-instance address of the application-supplied callback function. See the "Remarks" section below.

*`lpData`*\
Points to the application-supplied data. The data is passed to the callback function along with the object information.

### Return Value

Specifies the last value returned by the [callback function](callback-functions-used-by-mfc.md#enum_objects). Its meaning is user-defined.

### Remarks

For each object of a given type, the callback function that you pass is called with the information for that object. The system calls the callback function until there are no more objects or the callback function returns 0.

New features of Visual Studio let you use an ordinary function as the function passed to `EnumObjects`. The address passed to `EnumObjects` is a pointer to a function exported with **`EXPORT`** and with the Pascal calling convention. In protect-mode applications, you don't have to create this function with the Windows `MakeProcInstance` function or free the function after use with the `FreeProcInstance` Windows function.

You also don't have to export the function name in an **`EXPORTS`** statement in your application's module-definition file. You can instead use the **`EXPORT`** function modifier, as in

**int CALLBACK EXPORT** AFunction **(LPSTR**, **LPSTR);**

to cause the compiler to emit the proper export record for export by name without aliasing. This works for most needs. For some special cases, such as exporting a function by ordinal or aliasing the export, you still need to use an **`EXPORTS`** statement in a module-definition file.

For compiling Microsoft Foundation programs, you'll normally use the `/GA` and `/GEs` compiler options. The `/Gw` compiler option isn't used with the Microsoft Foundation classes. (If you do use the Windows function `MakeProcInstance`, you'll need to explicitly cast the returned function pointer from `FARPROC` to the type needed in this API.) Callback registration interfaces are now type-safe (you must pass in a function pointer that points to the right kind of function for the specific callback).

Also, all callback functions must trap Microsoft Foundation exceptions before returning to Windows, since exceptions cannot be thrown across callback boundaries. For more information about exceptions, see the article [Exceptions](../../mfc/exception-handling-in-mfc.md).

### Example

[!code-cpp[NVC_MFCDocView#35](../../mfc/codesnippet/cpp/cdc-class_7.cpp)]

## <a name="escape"></a> `CDC::Escape`

This member function is practically obsolete for Win32 programming.

```
virtual int Escape(
    int nEscape,
    int nCount,
    LPCSTR lpszInData,
    LPVOID lpOutData);

int Escape(
    int nEscape,
    int nInputSize,
    LPCSTR lpszInputData,
    int nOutputSize,
    LPSTR lpszOutputData);
```

### Parameters

*`nEscape`*\
Specifies the escape function to be performed.

For a complete list of escape functions, see [`Escape`](/windows/win32/api/wingdi/nf-wingdi-escape) in the Windows SDK.

*`nCount`*\
Specifies the number of bytes of data pointed to by *`lpszInData`*.

*`lpszInData`*\
Points to the input data structure required for this escape.

*`lpOutData`*\
Points to the structure that is to receive output from this escape. The *`lpOutData`* parameter is `NULL` if no data is returned.

*`nInputSize`*\
Specifies the number of bytes of data pointed to by the *`lpszInputData`* parameter.

*`lpszInputData`*\
Points to the input structure required for the specified escape.

*`nOutputSize`*\
Specifies the number of bytes of data pointed to by the *`lpszOutputData`* parameter.

*`lpszOutputData`*\
Points to the structure that receives output from this escape. This parameter should be `NULL` if no data is returned.

### Return Value

A positive value is returned if the function is successful, except for the `QUERYESCSUPPORT` escape, which only checks for implementation. Zero is returned if the escape isn't implemented. A negative value is returned if an error occurred. The following are common error values:

- `SP_ERROR` General error.

- `SP_OUTOFDISK` Not enough disk space is currently available for spooling, and no more space will become available.

- `SP_OUTOFMEMORY` Not enough memory is available for spooling.

- `SP_USERABORT` User ended the job through the Print Manager.

### Remarks

Of the original printer escapes, only `QUERYESCSUPPORT` is supported for Win32 applications. All other printer escapes are obsolete and are supported only for compatibility with 16-bit applications.

For Win32 programming, `CDC` now provides six member functions that supersede their corresponding printer escapes:

- [`CDC::AbortDoc`](#abortdoc)

- [`CDC::EndDoc`](#enddoc)

- [`CDC::EndPage`](#endpage)

- [`CDC::SetAbortProc`](#setabortproc)

- [`CDC::StartDoc`](#startdoc)

- [`CDC::StartPage`](#startpage)

In addition, [`CDC::GetDeviceCaps`](#getdevicecaps) supports Win32 indexes that supersede other printer escapes. See [`GetDeviceCaps`](/windows/win32/api/wingdi/nf-wingdi-getdevicecaps) in the Windows SDK for more information.

This member function allows applications to access facilities of a particular device that aren't directly available through GDI.

Use the first version if your application uses predefined escape values. Use the second version if your application defines private escape values. See [`ExtEscape`](/windows/win32/api/wingdi/nf-wingdi-extescape) in the Windows SDK for more information about the second version.

## <a name="excludecliprect"></a> `CDC::ExcludeClipRect`

Creates a new clipping region that consists of the existing clipping region minus the specified rectangle.

```
int ExcludeClipRect(
    int x1,
    int y1,
    int x2,
    int y2);

int ExcludeClipRect(LPCRECT lpRect);
```

### Parameters

*`x1`*\
Specifies the logical x-coordinate of the upper-left corner of the rectangle.

*`y1`*\
Specifies the logical y-coordinate of the upper-left corner of the rectangle.

*`x2`*\
Specifies the logical x-coordinate of the lower-right corner of the rectangle.

*`y2`*\
Specifies the logical y-coordinate of the lower-right corner of the rectangle.

*`lpRect`*\
Specifies the rectangle. Can also be a `CRect` object.

### Return Value

Specifies the new clipping region's type. It can be any of the following values:

- `COMPLEXREGION` The region has overlapping borders.

- `ERROR` No region was created.

- `NULLREGION` The region is empty.

- `SIMPLEREGION` The region has no overlapping borders.

### Remarks

The width of the rectangle, specified by the absolute value of *`x2`* - *`x1`*, must not exceed 32,767 units. This limit applies to the height of the rectangle as well.

## <a name="excludeupdatergn"></a> `CDC::ExcludeUpdateRgn`

Prevents drawing within invalid areas of a window by excluding an updated region in the window from the clipping region associated with the `CDC` object.

```
int ExcludeUpdateRgn(CWnd* pWnd);
```

### Parameters

*`pWnd`*\
Points to the window object whose window is being updated.

### Return Value

The type of excluded region. It can be any one of the following values:

- `COMPLEXREGION` The region has overlapping borders.

- `ERROR` No region was created.

- `NULLREGION` The region is empty.

- `SIMPLEREGION` The region has no overlapping borders.

## <a name="extfloodfill"></a> `CDC::ExtFloodFill`

Fills an area of the display surface with the current brush.

```
BOOL ExtFloodFill(
    int x,
    int y,
    COLORREF crColor,
    UINT nFillType);
```

### Parameters

*`x`*\
Specifies the logical x-coordinate of the point where filling begins.

*`y`*\
Specifies the logical y-coordinate of the point where filling begins.

*`crColor`*\
Specifies the color of the boundary or of the area to be filled. The interpretation of *`crColor`* depends on the value of *`nFillType`*.

*`nFillType`*\
Specifies the type of flood fill to be performed. It must be either of the following values:

- `FLOODFILLBORDER` The fill area is bounded by the color specified by *`crColor`*. This style is identical to the filling performed by `FloodFill`.

- `FLOODFILLSURFACE` The fill area is defined by the color specified by *`crColor`*. Filling continues outward in all directions as long as the color is encountered. This style is useful for filling areas with multicolored boundaries.

### Return Value

Nonzero if the function is successful; otherwise 0 if the filling couldn't be completed, if the given point has the boundary color specified by *`crColor`* (if `FLOODFILLBORDER` was requested), if the given point doesn't have the color specified by *`crColor`* (if `FLOODFILLSURFACE` was requested), or if the point is outside the clipping region.

### Remarks

This member function offers more flexibility than `FloodFill` because you can specify a fill type in *`nFillType`*.

If *`nFillType`* is set to `FLOODFILLBORDER`, the area is assumed to be completely bounded by the color specified by *`crColor`*. The function begins at the point specified by *`x`* and *`y`* and fills in all directions to the color boundary.

If *`nFillType`* is set to `FLOODFILLSURFACE`, the function begins at the point specified by *`x`* and *`y`* and continues in all directions, filling all adjacent areas containing the color specified by *`crColor`*.

Only memory-device contexts and devices that support raster-display technology support `ExtFloodFill`. For more information, see the [`GetDeviceCaps`](#getdevicecaps) member function.

## <a name="exttextout"></a> `CDC::ExtTextOut`

Call this member function to write a character string within a rectangular region using the currently selected font.

```
virtual BOOL ExtTextOut(
    int x,
    int y,
    UINT nOptions,
    LPCRECT lpRect,
    LPCTSTR lpszString,
    UINT nCount,
    LPINT lpDxWidths);

BOOL ExtTextOut(
    int x,
    int y,
    UINT nOptions,
    LPCRECT lpRect,
    const CString& str,
    LPINT lpDxWidths);
```

### Parameters

*`x`*\
Specifies the logical x-coordinate of the character cell for the first character in the specified string.

*`y`*\
Specifies the logical y-coordinate of the top of the character cell for the first character in the specified string.

*`nOptions`*\
Specifies the rectangle type. This parameter can be one, both, or neither of the following values:

- `ETO_CLIPPED` Specifies that text is clipped to the rectangle.

- `ETO_OPAQUE` Specifies that the current background color fills the rectangle. (You can set and query the current background color with the [`SetBkColor`](#setbkcolor) and [`GetBkColor`](#getbkcolor) member functions.)

*`lpRect`*\
Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure that determines the dimensions of the rectangle. This parameter can be `NULL`. You can also pass a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object for this parameter.

*`lpszString`*\
Points to the specified character string to be drawn. You can also pass a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object for this parameter.

*`nCount`*\
Specifies the number of characters in the string.

*`lpDxWidths`*\
Points to an array of values that indicate the distance between origins of adjacent character cells. For instance, *`lpDxWidths`*[ *`i`*] logical units will separate the origins of character cell *`i`* and character cell *`i`* + 1. If *`lpDxWidths`* is `NULL`, `ExtTextOut` uses the default spacing between characters.

*`str`*\
A `CString` object that contains the specified characters to be drawn.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The rectangular region can be opaque (filled with the current background color), and it can be a clipping region.

If *`nOptions`* is 0 and *`lpRect`* is `NULL`, the function writes text to the device context without using a rectangular region. By default, the current position isn't used or updated by the function. If an application needs to update the current position when it calls `ExtTextOut`, the application can call the `CDC` member function [`SetTextAlign`](#settextalign) with *`nFlags`* set to `TA_UPDATECP`. When this flag is set, Windows ignores *`x`* and *`y`* on subsequent calls to `ExtTextOut` and uses the current position instead. When an application uses `TA_UPDATECP` to update the current position, `ExtTextOut` sets the current position either to the end of the previous line of text or to the position specified by the last element of the array pointed to by *`lpDxWidths`*, whichever is greater.

## <a name="fillpath"></a> `CDC::FillPath`

Closes any open figures in the current path and fills the path's interior by using the current brush and polygon-filling mode.

```
BOOL FillPath();
```

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

After its interior is filled, the path is discarded from the device context.

## <a name="fillrect"></a> `CDC::FillRect`

Call this member function to fill a given rectangle using the specified brush.

```cpp
void FillRect(
    LPCRECT lpRect,
    CBrush* pBrush);
```

### Parameters

*`lpRect`*\
Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure that contains the logical coordinates of the rectangle to be filled. You can also pass a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object for this parameter.

*`pBrush`*\
Identifies the brush used to fill the rectangle.

### Remarks

The function fills the complete rectangle, including the left and top borders, but it doesn't fill the right and bottom borders.

The brush needs to either be created using the [`CBrush`](../../mfc/reference/cbrush-class.md) member functions [`CreateHatchBrush`](../../mfc/reference/cbrush-class.md#createhatchbrush), [`CreatePatternBrush`](../../mfc/reference/cbrush-class.md#createpatternbrush), and [`CreateSolidBrush`](../../mfc/reference/cbrush-class.md#createsolidbrush), or retrieved by the `GetStockObject` Windows function.

When filling the specified rectangle, `FillRect` doesn't include the rectangle's right and bottom sides. GDI fills a rectangle up to, but doesn't include, the right column and bottom row, regardless of the current mapping mode. `FillRect` compares the values of the `top`, `bottom`, `left`, and `right` members of the specified rectangle. If `bottom` is less than or equal to `top`, or if `right` is less than or equal to `left`, the rectangle isn't drawn.

`FillRect` is similar to [`CDC::FillSolidRect`](#fillsolidrect); however, `FillRect` takes a brush and therefore can be used to fill a rectangle with a solid color, a dithered color, hatched brushes, or a pattern. `FillSolidRect` uses only solid colors (indicated by a `COLORREF` parameter). `FillRect` usually is slower than `FillSolidRect`.

## <a name="fillrgn"></a> `CDC::FillRgn`

Fills the region specified by *`pRgn`* with the brush specified by *`pBrush`*.

```
BOOL FillRgn(
    CRgn* pRgn,
    CBrush* pBrush);
```

### Parameters

*`pRgn`*\
A pointer to the region to be filled. The coordinates for the given region are specified in logical units.

*`pBrush`*\
Identifies the brush to be used to fill the region.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The brush must either be created using the `CBrush` member functions `CreateHatchBrush`, `CreatePatternBrush`, `CreateSolidBrush`, or be retrieved by `GetStockObject`.

### Example

  See the example for [`CRgn::CreateRoundRectRgn`](../../mfc/reference/crgn-class.md#createroundrectrgn).

## <a name="fillsolidrect"></a> `CDC::FillSolidRect`

Call this member function to fill the given rectangle with the specified solid color.

```cpp
void FillSolidRect(
    LPCRECT lpRect,
    COLORREF clr);

void FillSolidRect(
    int x,
    int y,
    int cx,
    int cy,
    COLORREF clr);
```

### Parameters

*`lpRect`*\
Specifies the bounding rectangle (in logical units). You can pass either a pointer to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) data structure or a `CRect` object for this parameter.

*`clr`* Specifies the color to be used to fill the rectangle.

*`x`*\
Specifies the logical x-coordinate of the upper-left corner of the rectangle.

*`y`*\
Specifies the logical y-coordinate of the upper-left corner of the destination rectangle.

*`cx`*\
Specifies the width of the rectangle.

*`cy`*\
Specifies the height of the rectangle.

### Remarks

`FillSolidRect` is very similar to [`CDC::FillRect`](#fillrect); however, `FillSolidRect` uses only solid colors (indicated by the `COLORREF` parameter), while `FillRect` takes a brush and therefore can be used to fill a rectangle with a solid color, a dithered color, hatched brushes, or a pattern. `FillSolidRect` usually is faster than `FillRect`.

> [!NOTE]
> When you call `FillSolidRect`, the background color, which was previously set using [`SetBkColor`](#setbkcolor), is set to the color indicated by *`clr`*.

## <a name="flattenpath"></a> `CDC::FlattenPath`

Transforms any curves in the path selected into the current device context, and turns each curve into a sequence of lines.

```
BOOL FlattenPath();
```

### Return Value

Nonzero if the function is successful; otherwise 0.

## <a name="floodfill"></a> `CDC::FloodFill`

Fills an area of the display surface with the current brush.

```
BOOL FloodFill(
    int x,
    int y,
    COLORREF crColor);
```

### Parameters

*`x`*\
Specifies the logical x-coordinate of the point where filling begins.

*`y`*\
Specifies the logical y-coordinate of the point where filling begins.

*`crColor`*\
Specifies the color of the boundary.

### Return Value

Nonzero if the function is successful; otherwise 0 is returned if the filling couldn't be completed, the given point has the boundary color specified by *`crColor`*, or the point is outside the clipping region.

### Remarks

The area is assumed to be bounded as specified by *`crColor`*. The `FloodFill` function begins at the point specified by *`x`* and *`y`* and continues in all directions to the color boundary.

Only memory-device contexts and devices that support raster-display technology support the `FloodFill` member function. For information about `RC_BITBLT` capability, see the `GetDeviceCaps` member function.

The `ExtFloodFill` function provides similar capability but greater flexibility.

## <a name="framerect"></a> `CDC::FrameRect`

Draws a border around the rectangle specified by *`lpRect`*.

```cpp
void FrameRect(
    LPCRECT lpRect,
    CBrush* pBrush);
```

### Parameters

*`lpRect`*\
Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that contains the logical coordinates of the upper-left and lower-right corners of the rectangle. You can also pass a `CRect` object for this parameter.

*`pBrush`*\
Identifies the brush to be used for framing the rectangle.

### Remarks

The function uses the given brush to draw the border. The width and height of the border is always 1 logical unit.

If the rectangle's `bottom` coordinate is less than or equal to `top`, or if `right` is less than or equal to `left`, the rectangle isn't drawn.

The border drawn by `FrameRect` is in the same position as a border drawn by the `Rectangle` member function using the same coordinates (if `Rectangle` uses a pen that is 1 logical unit wide). The interior of the rectangle isn't filled by `FrameRect`.

## <a name="framergn"></a> `CDC::FrameRgn`

Draws a border around the region specified by *`pRgn`* using the brush specified by *`pBrush`*.

```
BOOL FrameRgn(
    CRgn* pRgn,
    CBrush* pBrush,
    int nWidth,
    int nHeight);
```

### Parameters

*`pRgn`*\
Points to the `CRgn` object that identifies the region to be enclosed in a border. The coordinates for the given region are specified in logical units.

*`pBrush`*\
Points to the `CBrush` object that identifies the brush to be used to draw the border.

*`nWidth`*\
Specifies the width of the border in vertical brush strokes in device units.

*`nHeight`*\
Specifies the height of the border in horizontal brush strokes in device units.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Example

  See the example for [`CRgn::CombineRgn`](../../mfc/reference/crgn-class.md#combinergn).

## <a name="fromhandle"></a> `CDC::FromHandle`

Returns a pointer to a `CDC` object when given a handle to a device context.

```
static CDC* PASCAL FromHandle(HDC hDC);
```

### Parameters

*`hDC`*\
Contains a handle to a Windows device context.

### Return Value

The pointer may be temporary and shouldn't be stored beyond immediate use.

### Remarks

If a `CDC` object isn't attached to the handle, a temporary `CDC` object is created and attached.

### Example

  See the example for [`CPrintDialog::GetPrinterDC`](../../mfc/reference/cprintdialog-class.md#getprinterdc).

## <a name="getarcdirection"></a> `CDC::GetArcDirection`

Returns the current arc direction for the device context.

```
int GetArcDirection() const;
```

### Return Value

Specifies the current arc direction, if successful. Following are the valid return values:

- `AD_COUNTERCLOCKWISE` Arcs and rectangles drawn counterclockwise.

- `AD_CLOCKWISE Arcs` and rectangles drawn clockwise.

If an error occurs, the return value is zero.

### Remarks

Arc and rectangle functions use the arc direction.

## <a name="getaspectratiofilter"></a> `CDC::GetAspectRatioFilter`

Retrieves the setting for the current aspect-ratio filter.

```
CSize GetAspectRatioFilter() const;
```

### Return Value

A `CSize` object representing the aspect ratio used by the current aspect ratio filter.

### Remarks

The aspect ratio is the ratio formed by a device's pixel width and height. Information about a device's aspect ratio is used in the creation, selection, and display of fonts. Windows provides a special filter, the aspect-ratio filter, to select fonts designed for a particular aspect ratio from all of the available fonts. The filter uses the aspect ratio specified by the `SetMapperFlags` member function.

## <a name="getbkcolor"></a> `CDC::GetBkColor`

Returns the current background color.

```
COLORREF GetBkColor() const;
```

### Return Value

An RGB color value.

### Remarks

If the background mode is `OPAQUE`, the system uses the background color to fill the gaps in styled lines, the gaps between hatched lines in brushes, and the background in character cells. The system also uses the background color when converting bitmaps between color and monochrome device contexts.

## <a name="getbkmode"></a> CDC::GetBkMode

Returns the background mode.

```
int GetBkMode() const;
```

### Return Value

The current background mode, which can be `OPAQUE` or `TRANSPARENT`.

### Remarks

The background mode defines whether the system removes existing background colors on the drawing surface before drawing text, hatched brushes, or any pen style that isn't a solid line.

## <a name="getboundsrect"></a> `CDC::GetBoundsRect`

Returns the current accumulated bounding rectangle for the specified device context.

```
UINT GetBoundsRect(
    LPRECT lpRectBounds,
    UINT flags);
```

### Parameters

*`lpRectBounds`*\
Points to a buffer that will receive the current bounding rectangle. The rectangle is returned in logical coordinates.

*`flags`*\
Specifies whether the bounding rectangle is to be cleared after it's returned. This parameter should be zero or set to the following value:

- `DCB_RESET` Forces the bounding rectangle to be cleared after it's returned.

### Return Value

Specifies the current state of the bounding rectangle if the function is successful. It can be a combination of the following values:

- `DCB_ACCUMULATE` Bounding rectangle accumulation is occurring.

- `DCB_RESET` Bounding rectangle is empty.

- `DCB_SET` Bounding rectangle isn't empty.

- `DCB_ENABLE` Bounding accumulation is on.

- `DCB_DISABLE` Bounding accumulation is off.

## <a name="getbrushorg"></a> `CDC::GetBrushOrg`

Retrieves the origin (in device units) of the brush currently selected for the device context.

```
CPoint GetBrushOrg() const;
```

### Return Value

The current origin of the brush (in device units) as a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object.

### Remarks

The initial brush origin is at (0,0) of the client area. The return value specifies this point in device units relative to the origin of the desktop window.

## <a name="getcharacterplacement"></a> `CDC::GetCharacterPlacement`

Retrieves various types of information on a character string.

```
DWORD GetCharacterPlacement(
    LPCTSTR lpString,
    int nCount,
    int nMaxExtent,
    LPGCP_RESULTS lpResults,
    DWORD dwFlags) const;

DWORD GetCharacterPlacement(
    CString& str,
    int nMaxExtent,
    LPGCP_RESULTS lpResults,
    DWORD dwFlags) const;
```

### Parameters

*`lpString`*\
A pointer to the character string to process.

*`nCount`*\
Specifies the length of the string. For the ANSI version, it's a `BYTE` count and for the Unicode function it's a `WORD` count. For more information, see [`GetCharacterPlacement`](/windows/win32/api/wingdi/nf-wingdi-getcharacterplacementw).

*`nMaxExtent`*\
Specifies the maximum extent (in logical units) to which the string is processed. Characters that, if processed, would exceed this extent are ignored. Computations for any required ordering or glyph arrays apply only to the included characters. This parameter is used only if the `GCP_MAXEXTENT` value is specified in the *`dwFlags`* parameter. As the function processes the input string, each character and its extent is added to the output, extent, and other arrays only if the total extent has not yet exceeded the maximum. Once the limit is reached, processing will stop.

*`lpResults`*\
Pointer to a [`GCP_Results`](/windows/win32/api/wingdi/ns-wingdi-gcp_resultsw) structure that receives the results of the function.

*`dwFlags`*\
Specifies how to process the string into the required arrays. This parameter can be one or more of the values listed in the *`dwFlags`* section of the [`GetCharacterPlacement`](/windows/win32/api/wingdi/nf-wingdi-getcharacterplacementw) topic.

*`str`*\
A pointer to a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object to process.

### Return Value

If the function succeeds, the return value is the width and height of the string in logical units.

If the function fails, the return value is zero.

### Remarks

This member function emulates the functionality of the function [`GetCharacterPlacement`](/windows/win32/api/wingdi/nf-wingdi-getcharacterplacementw), as described in the Windows SDK.

## <a name="getcharabcwidths"></a> `CDC::GetCharABCWidths`

Retrieves the widths of consecutive characters in a specified range from the current TrueType font.

```
BOOL GetCharABCWidths(
    UINT nFirstChar,
    UINT nLastChar,
    LPABC lpabc) const;

BOOL GetCharABCWidths(
    UINT nFirstChar,
    UINT nLastChar,
    LPABCFLOAT lpABCF) const;
```

### Parameters

*`nFirstChar`*\
Specifies the first character in the range of characters from the current font for which character widths are returned.

*`nLastChar`*\
Specifies the last character in the range of characters from the current font for which character widths are returned.

*`lpabc`*\
Points to an array of [`ABC`](/windows/win32/api/wingdi/ns-wingdi-abc) structures that receive the character widths when the function returns. This array must contain at least as many `ABC` structures as there are characters in the range specified by the *`nFirstChar`* and *`nLastChar`* parameters.

*`lpABCF`*\
Points to an application-supplied buffer with an array of [`ABCFLOAT`](/windows/win32/api/wingdi/ns-wingdi-abcfloat) structures to receive the character widths when the function returns. The widths returned by this function are in the IEEE floating-point format.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The widths are returned in logical units. This function succeeds only with TrueType fonts.

The TrueType rasterizer provides "ABC" character spacing after a specific point size has been selected. "A" spacing is the distance that is added to the current position before placing the glyph. "B" spacing is the width of the black part of the glyph. "C" spacing is added to the current position to account for the white space to the right of the glyph. The total advanced width is given by A + B + C.

When the `GetCharABCWidths` member function retrieves negative "A" or "C" widths for a character, that character includes underhangs or overhangs.

To convert the ABC widths to font design units, an application should create a font whose height (as specified in the `lfHeight` member of the [`LOGFONT`](/windows/win32/api/wingdi/ns-wingdi-logfontw) structure) is equal to the value stored in the `ntmSizeEM` member of the [`NEWTEXTMETRIC`](/windows/win32/api/wingdi/ns-wingdi-newtextmetricw) structure. (The value of the `ntmSizeEM` member can be retrieved by calling the [`EnumFontFamilies`](/windows/win32/api/wingdi/nf-wingdi-enumfontfamiliesw) Windows function.)

The ABC widths of the default character are used for characters that are outside the range of the currently selected font.

To retrieve the widths of characters in non-TrueType fonts, applications should use the [`GetCharWidth`](/windows/win32/api/wingdi/nf-wingdi-getcharwidthw) Windows function.

## <a name="getcharabcwidthsi"></a> `CDC::GetCharABCWidthsI`

Retrieves the widths, in logical units, of consecutive glyph indices in a specified range from the current TrueType font.

```
BOOL GetCharABCWidthsI(
    UINT giFirst,
    UINT cgi,
    LPWORD pgi,
    LPABC lpabc) const;
```

### Parameters

*`giFirst`*\
Specifies the first glyph index in the group of consecutive glyph indices from the current font. This parameter is only used if the *`pgi`* parameter is `NULL`.

*`cgi`*\
Specifies the number of glyph indices.

*`pgi`*\
A pointer to an array containing glyph indices. If the value is `NULL`, the *`giFirst`* parameter is used instead. The *`cgi`* parameter specifies the number of glyph indices in this array.

*`lpabc`*\
Pointer to an array of [`ABC`](/windows/win32/api/wingdi/ns-wingdi-abc) structures receiving the character widths. This array must contain at least as many `ABC` structures as there are glyph indices specified by the *`cgi`* parameter.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

This member function emulates the functionality of the function [`GetCharABCWidthsI`](/windows/win32/api/wingdi/nf-wingdi-getcharabcwidthsi), as described in the Windows SDK.

## <a name="getcharwidth"></a> `CDC::GetCharWidth`

Retrieves the widths of individual characters in a consecutive group of characters from the current font, using `m_hAttribDC`, the input device context.

```
BOOL GetCharWidth(
    UINT nFirstChar,
    UINT nLastChar,
    LPINT lpBuffer) const;

BOOL GetCharWidth(
    UINT nFirstChar,
    UINT nLastChar,
    float* lpFloatBuffer) const;
```

### Parameters

*`nFirstChar`*\
Specifies the first character in a consecutive group of characters in the current font.

*`nLastChar`*\
Specifies the last character in a consecutive group of characters in the current font.

*`lpBuffer`*\
Points to a buffer that will receive the width values for a consecutive group of characters in the current font.

*`lpFloatBuffer`*\
Points to a buffer to receive the character widths. The returned widths are in the 32-bit IEEE floating-point format. (The widths are measured along the base line of the characters.)

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

For example, if *`nFirstChar`* identifies the letter 'a' and *`nLastChar`* identifies the letter 'z', the function retrieves the widths of all lowercase characters.

The function stores the values in the buffer pointed to by *`lpBuffer`*. This buffer must be large enough to hold all of the widths. That is, there must be at least 26 entries in the example given.

If a character in the consecutive group of characters doesn't exist in a particular font, it will be assigned the width value of the default character.

## <a name="getcharwidthi"></a> `CDC::GetCharWidthI`

Retrieves the widths, in logical coordinates, of consecutive glyph indices in a specified range from the current font.

```
BOOL GetCharWidthI(
    UINT giFirst,
    UINT cgi,
    LPWORD pgi,
    LPINT lpBuffer) const;
```

### Parameters

*`giFirst`*\
Specifies the first glyph index in the group of consecutive glyph indices from the current font. This parameter is only used if the *`pgi`* parameter is `NULL`.

*`cgi`*\
Specifies the number of glyph indices.

*`pgi`*\
A pointer to an array containing glyph indices. If the value is `NULL`, the *`giFirst`* parameter is used instead. The *`cgi`* parameter specifies the number of glyph indices in this array.

*`lpBuffer`*\
A pointer to a buffer that receives the widths.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

This member function emulates the functionality of the function [`GetCharWidthI`](/windows/win32/api/wingdi/nf-wingdi-getcharwidthi), as described in the Windows SDK.

## <a name="getclipbox"></a> `CDC::GetClipBox`

Retrieves the dimensions of the tightest bounding rectangle around the current clipping boundary.

```
virtual int GetClipBox(LPRECT lpRect) const;
```

### Parameters

*`lpRect`*\
Points to the [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that is to receive the rectangle dimensions.

### Return Value

The clipping region's type. It can be any of the following values:

- `COMPLEXREGION` Clipping region has overlapping borders.

- `ERROR` Device context isn't valid.

- `NULLREGION` Clipping region is empty.

- `SIMPLEREGION` Clipping region has no overlapping borders.

### Remarks

The dimensions are copied to the buffer pointed to by *`lpRect`*.

## <a name="getcoloradjustment"></a> `CDC::GetColorAdjustment`

Retrieves the color adjustment values for the device context.

```
BOOL GetColorAdjustment(LPCOLORADJUSTMENT lpColorAdjust) const;
```

### Parameters

*`lpColorAdjust`*\
Points to a [`COLORADJUSTMENT`](/windows/win32/api/wingdi/ns-wingdi-coloradjustment) data structure to receive the color adjustment values.

### Return Value

Nonzero if the function is successful; otherwise 0.

## <a name="getcurrentbitmap"></a> `CDC::GetCurrentBitmap`

Returns a pointer to the currently selected `CBitmap` object.

```
CBitmap* GetCurrentBitmap() const;
```

### Return Value

Pointer to a `CBitmap` object, if successful; otherwise `NULL`.

### Remarks

This member function may return temporary objects.

## <a name="getcurrentbrush"></a> `CDC::GetCurrentBrush`

Returns a pointer to the currently selected `CBrush` object.

```
CBrush* GetCurrentBrush() const;
```

### Return Value

Pointer to a `CBrush` object, if successful; otherwise `NULL`.

### Remarks

This member function may return temporary objects.

## <a name="getcurrentfont"></a> `CDC::GetCurrentFont`

Returns a pointer to the currently selected `CFont` object.

```
CFont* GetCurrentFont() const;
```

### Return Value

Pointer to a `CFont` object, if successful; otherwise `NULL`.

### Remarks

This member function may return temporary objects.

## <a name="getcurrentpalette"></a> `CDC::GetCurrentPalette`

Returns a pointer to the currently selected `CPalette` object.

```
CPalette* GetCurrentPalette() const;
```

### Return Value

Pointer to a `CPalette` object, if successful; otherwise `NULL`.

### Remarks

This member function may return temporary objects.

## <a name="getcurrentpen"></a> `CDC::GetCurrentPen`

Returns a pointer to the currently selected `CPen` object.

```
CPen* GetCurrentPen() const;
```

### Return Value

Pointer to a `CPen` object, if successful; otherwise `NULL`.

### Remarks

This member function may return temporary objects.

## <a name="getcurrentposition"></a> `CDC::GetCurrentPosition`

Retrieves the current position (in logical coordinates).

```
CPoint GetCurrentPosition() const;
```

### Return Value

The current position as a `CPoint` object.

### Remarks

The current position can be set with the `MoveTo` member function.

## <a name="getdcbrushcolor"></a> `CDC::GetDCBrushColor`

Retrieves the current brush color.

```
COLORREF GetDCBrushColor() const;
```

### Return Value

If the function succeeds, the return value is the [`COLORREF`](/windows/win32/gdi/colorref) value for the current brush color.

If the function fails, the return value is `CLR_INVALID`.

### Remarks

This member function emulates the functionality of the function [`GetDCBrushColor`](/windows/win32/api/wingdi/nf-wingdi-getdcbrushcolor), as described in the Windows SDK.

## <a name="getdcpencolor"></a> `CDC::GetDCPenColor`

Retrieves the current pen color.

```
COLORREF GetDCPenColor() const;
```

### Return Value

If the function succeeds, the return value is the [`COLORREF`](/windows/win32/gdi/colorref) value for the current pen color.

If the function fails, the return value is `CLR_INVALID`.

### Remarks

This member function utilizes the Win32 function [`GetDCPenColor`](/windows/win32/api/wingdi/nf-wingdi-getdcpencolor), as described in the Windows SDK.

## <a name="getdevicecaps"></a> `CDC::GetDeviceCaps`

Retrieves a wide range of device-specific information about the display device.

```
int GetDeviceCaps(int nIndex) const;
```

### Parameters

*`nIndex`*\
Specifies the type of information to return. See [`GetDeviceCaps`](/windows/win32/api/wingdi/nf-wingdi-getdevicecaps) in the Windows SDK for a list of values.

### Return Value

The value of the requested capability if the function is successful.

### Example

  See the example for [`CPrintDialog::GetDefaults`](../../mfc/reference/cprintdialog-class.md#getdefaults).

## <a name="getfontdata"></a> `CDC::GetFontData`

Retrieves font-metric information from a scalable font file.

```
DWORD GetFontData(
    DWORD dwTable,
    DWORD dwOffset,
    LPVOID lpData,
    DWORD cbData) const;
```

### Parameters

*`dwTable`*\
Specifies the name of the metric table to be returned. This parameter can be one of the metric tables documented in the TrueType Font Files specification published by Microsoft Corporation. If this parameter is 0, the information is retrieved starting at the beginning of the font file.

*`dwOffset`*\
Specifies the offset from the beginning of the table at which to begin retrieving information. If this parameter is 0, the information is retrieved starting at the beginning of the table specified by the *`dwTable`* parameter. If this value is greater than or equal to the size of the table, `GetFontData` returns 0.

*`lpData`*\
Points to a buffer that will receive the font information. If this value is `NULL`, the function returns the size of the buffer required for the font data specified in the *`dwTable`* parameter.

*`cbData`*\
Specifies the length, in bytes, of the information to be retrieved. If this parameter is 0, `GetFontData` returns the size of the data specified in the *`dwTable`* parameter.

### Return Value

Specifies the number of bytes returned in the buffer pointed to by *`lpData`* if the function is successful; otherwise -1.

### Remarks

The information to retrieve is identified by specifying an offset into the font file and the length of the information to return.

An application can sometimes use the `GetFontData` member function to save a TrueType font with a document. To do this, the application determines whether the font can be embedded and then retrieves the entire font file, specifying 0 for the *`dwTable`*, *`dwOffset`*, and *`cbData`* parameters.

Applications can determine whether a font can be embedded by checking the `otmfsType` member of the [`OUTLINETEXTMETRIC`](/windows/win32/api/wingdi/ns-wingdi-outlinetextmetricw) structure. If bit 1 of `otmfsType` is set, embedding isn't permitted for the font. If bit 1 is clear, the font can be embedded. If bit 2 is set, the embedding is read only.

If an application attempts to use this function to retrieve information for a non-TrueType font, the `GetFontData` member function returns -1.

## <a name="getfontlanguageinfo"></a> `CDC::GetFontLanguageInfo`

Returns information about the currently selected font for the specified display context.

```
DWORD GetFontLanguageInfo() const;
```

### Return Value

The return value identifies characteristics of the currently selected font. For a complete listing of possible values, see [`GetFontLanguageInfo`](/windows/win32/api/wingdi/nf-wingdi-getfontlanguageinfo).

### Remarks

This member function emulates the functionality of the function [`GetFontLanguageInfo`](/windows/win32/api/wingdi/nf-wingdi-getfontlanguageinfo), as described in the Windows SDK.

## <a name="getglyphoutline"></a> `CDC::GetGlyphOutline`

Retrieves the outline curve or bitmap for an outline character in the current font.

```
DWORD GetGlyphOutline(
    UINT nChar,
    UINT nFormat,
    LPGLYPHMETRICS lpgm,
    DWORD cbBuffer,
    LPVOID lpBuffer,
    const MAT2* lpmat2) const;
```

### Parameters

*`nChar`*\
Specifies the character for which information is to be returned.

*`nFormat`*\
Specifies the format in which the function is to return information. It can be one of the following values, or 0:

|Value|Meaning|
|-----------|-------------|
|`GGO_BITMAP`|Returns the glyph bitmap. When the function returns, the buffer pointed to by *`lpBuffer`* contains a 1-bit-per-pixel bitmap whose rows start on doubleword boundaries.|
|`GGO_NATIVE`|Returns the curve data points in the rasterizer's native format, using device units. When this value is specified, any transformation specified in *`lpmat2`* is ignored.|

When the value of *`nFormat`* is 0, the function fills in a [`GLYPHMETRICS`](/windows/win32/api/wingdi/ns-wingdi-glyphmetrics) structure but doesn't return glyph-outline data.

*`lpgm`*\
Points to a `GLYPHMETRICS` structure that describes the placement of the glyph in the character cell.

*`cbBuffer`*\
Specifies the size of the buffer into which the function copies information about the outline character. If this value is 0 and the *`nFormat`* parameter is either the `GGO_BITMAP` or `GGO_NATIVE` values, the function returns the required size of the buffer.

*`lpBuffer`*\
Points to a buffer into which the function copies information about the outline character. If *`nFormat`* specifies the `GGO_NATIVE` value, the information is copied in the form of `TTPOLYGONHEADER` and `TTPOLYCURVE` structures. If this value is `NULL` and *`nFormat`* is either the `GGO_BITMAP` or `GGO_NATIVE` value, the function returns the required size of the buffer.

*`lpmat2`*\
Points to a [`MAT2`](/windows/win32/api/wingdi/ns-wingdi-mat2) structure that contains a transformation matrix for the character. This parameter cannot be `NULL`, even when the `GGO_NATIVE` value is specified for *`nFormat`*.

### Return Value

The size, in bytes, of the buffer required for the retrieved information if *`cbBuffer`* is 0 or *`lpBuffer`* is `NULL`. Otherwise, it's a positive value if the function is successful, or -1 if there's an error.

### Remarks

An application can rotate characters retrieved in bitmap format by specifying a 2-by-2 transformation matrix in the structure pointed to by *`lpmat2`*.

A glyph outline is returned as a series of contours. Each contour is defined by a [`TTPOLYGONHEADER`](/windows/win32/api/wingdi/ns-wingdi-ttpolygonheader) structure followed by as many `TTPOLYCURVE` structures as are required to describe it. All points are returned as [`POINTFX`](/windows/win32/api/wingdi/ns-wingdi-pointfx) structures and represent absolute positions, not relative moves. The starting point given by the `pfxStart` member of the [`TTPOLYGONHEADER`](/windows/win32/api/wingdi/ns-wingdi-ttpolygonheader) structure is the point at which the outline for a contour begins. The [`TTPOLYCURVE`](/windows/win32/api/wingdi/ns-wingdi-ttpolycurve) structures that follow can be either polyline records or spline records. Polyline records are a series of points; lines drawn between the points describe the outline of the character. Spline records represent the quadratic curves used by TrueType (that is, quadratic b-splines).

## <a name="getgraphicsmode"></a> `CDC::GetGraphicsMode`

Retrieves the current graphics mode for the specified device context.

```
int GetGraphicsMode() const;
```

### Return Value

Returns the current graphics mode on success. For a list of the values that this method can return, see [`GetGraphicsMode`](/windows/win32/api/wingdi/nf-wingdi-getgraphicsmode).

Returns 0 on failure.

To get extended error information, call [`GetLastError`](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror).

### Remarks

This method wraps the Windows GDI function [`GetGraphicsMode`](/windows/win32/api/wingdi/nf-wingdi-getgraphicsmode).

## <a name="gethalftonebrush"></a> `CDC::GetHalftoneBrush`

Call this member function to retrieve a halftone brush.

```
static CBrush* PASCAL GetHalftoneBrush();
```

### Return Value

A pointer to a `CBrush` object if successful; otherwise `NULL`.

### Remarks

A halftone brush shows pixels that are alternately foreground and background colors to create a dithered pattern. The following diagram shows an example of a dithered pattern created by a halftone brush:

:::image type="complex" source="../../mfc/reference/media/vc318s1.gif" alt-text="Diagram that shows how a dithered pen stroke is composed.":::
The diagram shows how the background color of black, and the foreground color of yellow, are combined into a pattern by alternating the black and yellow pixels with each other to create a dithered pen stroke.
:::image-end:::  

## <a name="getkerningpairs"></a> `CDC::GetKerningPairs`

Retrieves the character kerning pairs for the font that is currently selected in the specified device context.

```
int GetKerningPairs(
    int nPairs,
    LPKERNINGPAIR lpkrnpair) const;
```

### Parameters

*`nPairs`*\
Specifies the number of [`KERNINGPAIR`](/windows/win32/api/wingdi/ns-wingdi-kerningpair) structures pointed to by *`lpkrnpair`*. The function won't copy more kerning pairs than specified by *`nPairs`*.

*`lpkrnpair`*\
Points to an array of `KERNINGPAIR` structures that receive the kerning pairs when the function returns. This array must contain at least as many structures as specified by *`nPairs`*. If this parameter is `NULL`, the function returns the total number of kerning pairs for the font.

### Return Value

Specifies the number of kerning pairs retrieved or the total number of kerning pairs in the font, if the function is successful. Zero is returned if the function fails or there are no kerning pairs for the font.

## <a name="getlayout"></a> `CDC::GetLayout`

Call this member function to determine the layout of the text and graphics for a device context, such as a printer or a metafile.

```
DWORD GetLayout() const;
```

### Return Value

If successful, the layout flags for the current device context. Otherwise, `GDI_ERROR`. For extended error information, call [`GetLastError`](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror). For a list of the layout flags, see [`CDC::SetLayout`](#setlayout).

### Remarks

The default layout is left to right.

## <a name="getmapmode"></a> `CDC::GetMapMode`

Retrieves the current mapping mode.

```
int GetMapMode() const;
```

### Return Value

The mapping mode.

### Remarks

For a description of the mapping modes, see the `SetMapMode` member function.

> [!NOTE]
> If you call [`SetLayout`](#setlayout) to change the DC to right-to-left layout, `SetLayout` automatically changes the mapping mode to `MM_ISOTROPIC`. Consequently, any subsequent call to `GetMapMode` will return `MM_ISOTROPIC`.

## <a name="getmiterlimit"></a> `CDC::GetMiterLimit`

Returns the miter limit for the device context.

```
float GetMiterLimit() const;
```

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The miter limit is used when drawing geometric lines that have miter joins.

## <a name="getnearestcolor"></a> `CDC::GetNearestColor`

Returns the solid color that best matches a specified logical color.

```
COLORREF GetNearestColor(COLORREF crColor) const;
```

### Parameters

*`crColor`*\
Specifies the color to be matched.

### Return Value

An RGB (red, green, blue) color value that defines the solid color closest to the *`crColor`* value that the device can represent.

### Remarks

The given device must be able to represent this color.

## <a name="getoutlinetextmetrics"></a> `CDC::GetOutlineTextMetrics`

Retrieves metric information for TrueType fonts.

```
UINT GetOutlineTextMetrics(
    UINT cbData,
    LPOUTLINETEXTMETRIC lpotm) const;
```

### Parameters

*`lpotm`*\
Points to an array of [`OUTLINETEXTMETRIC`](/windows/win32/api/wingdi/ns-wingdi-outlinetextmetricw) structures. If this parameter is `NULL`, the function returns the size of the buffer required for the retrieved metric data.

*`cbData`*\
Specifies the size, in bytes, of the buffer to which information is returned.

*`lpotm`*\
Points to an `OUTLINETEXTMETRIC` structure. If this parameter is `NULL`, the function returns the size of the buffer required for the retrieved metric information.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The [`OUTLINETEXTMETRIC`](/windows/win32/api/wingdi/ns-wingdi-outlinetextmetricw) structure contains most of the font metric information provided with the TrueType format, including a [`TEXTMETRIC`](/windows/win32/api/wingdi/ns-wingdi-textmetricw) structure. The last four members of the `OUTLINETEXTMETRIC` structure are pointers to strings. Applications should allocate space for these strings in addition to the space required for the other members. Because there's no system-imposed limit to the size of the strings, the simplest method for allocating memory is to retrieve the required size by specifying NULL for *`lpotm`* in the first call to the `GetOutlineTextMetrics` function.

## <a name="getoutputcharwidth"></a> `CDC::GetOutputCharWidth`

Uses the output device context, `m_hDC`, and retrieves the widths of individual characters in a consecutive group of characters from the current font.

```
BOOL GetOutputCharWidth(
    UINT nFirstChar,
    UINT nLastChar,
    LPINT lpBuffer) const;
```

### Parameters

*`nFirstChar`*\
Specifies the first character in a consecutive group of characters in the current font.

*`nLastChar`*\
Specifies the last character in a consecutive group of characters in the current font.

*`lpBuffer`*\
Points to a buffer that will receive the width values for a consecutive group of characters in the current font.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

For example, if *`nFirstChar`* identifies the letter 'a' and *`nLastChar`* identifies the letter 'z', the function retrieves the widths of all lowercase characters.

The function stores the values in the buffer pointed to by *`lpBuffer`*. This buffer must be large enough to hold all of the widths; that is, there must be at least 26 entries in the example given.

If a character in the consecutive group of characters doesn't exist in a particular font, it will be assigned the width value of the default character.

## <a name="getoutputtabbedtextextent"></a> `CDC::GetOutputTabbedTextExtent`

Call this member function to compute the width and height of a character string using [`m_hDC`](#m_hdc), the output device context.

```
CSize GetOutputTabbedTextExtent(
    LPCTSTR lpszString,
    int nCount,
    int nTabPositions,
    LPINT lpnTabStopPositions) const;

CSize GetOutputTabbedTextExtent(
    const CString& str,
    int nTabPositions,
    LPINT lpnTabStopPositions) const;
```

### Parameters

*`lpszString`*\
Points to a character string to be measured. You can also pass a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object for this parameter.

*`nCount`*\
Specifies the [length of the string](/windows/win32/gdi/specifying-length-of-text-output-string) pointed to by *`lpszString`*.

*`nTabPositions`*\
Specifies the number of tab-stop positions in the array pointed to by *`lpnTabStopPositions`*.

*`lpnTabStopPositions`*\
Points to an array of integers containing the tab-stop positions in logical units. The tab stops must be sorted in increasing order; the smallest x-value should be the first item in the array. Back tabs aren't allowed.

*`str`*\
A `CString` object that contains the specified characters to be measured.

### Return Value

The dimensions of the string (in logical units) in a [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object.

### Remarks

If the string contains one or more tab characters, the width of the string is based upon the tab stops specified by *`lpnTabStopPositions`*. The function uses the currently selected font to compute the dimensions of the string.

The current clipping region doesn't offset the width and height returned by the `GetOutputTabbedTextExtent` function.

Since some devices don't place characters in regular cell arrays (that is, they kern the characters), the sum of the extents of the characters in a string may not be equal to the extent of the string.

If *`nTabPositions`* is 0 and *`lpnTabStopPositions`* is `NULL`, tabs are expanded to eight average character widths. If *`nTabPositions`* is 1, the tab stops will be separated by the distance specified by the first value in the array to which *`lpnTabStopPositions`* points. If *`lpnTabStopPositions`* points to more than a single value, a tab stop is set for each value in the array, up to the number specified by *`nTabPositions`*.

## <a name="getoutputtextextent"></a> `CDC::GetOutputTextExtent`

Call this member function to use the output device context, [`m_hDC`](#m_hdc), and compute the width and height of a line of text, using the current font.

```
CSize GetOutputTextExtent(
    LPCTSTR lpszString,
    int nCount) const;

CSize GetOutputTextExtent(const CString& str) const;
```

### Parameters

*`lpszString`*\
Points to a string of characters. You can also pass a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object for this parameter.

*`nCount`*\
Specifies the [length of the string](/windows/win32/gdi/specifying-length-of-text-output-string) pointed to by *`lpszString`*.

*`str`*\
A `CString` object that contains the specified characters to be measured.

### Return Value

The dimensions of the string (in logical units) returned in a [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object.

### Remarks

The current clipping region doesn't affect the width and height returned by `GetOutputTextExtent`.

Since some devices don't place characters in regular cell arrays (that is, they carry out kerning), the sum of the extents of the characters in a string may not be equal to the extent of the string.

## <a name="getoutputtextmetrics"></a> `CDC::GetOutputTextMetrics`

Retrieves the metrics for the current font using `m_hDC`, the output device context.

```
BOOL GetOutputTextMetrics(LPTEXTMETRIC lpMetrics) const;
```

### Parameters

*`lpMetrics`*\
Points to the [`TEXTMETRIC`](/windows/win32/api/wingdi/ns-wingdi-textmetricw) structure that receives the metrics.

### Return Value

Nonzero if the function is successful; otherwise 0.

## <a name="getpath"></a> `CDC::GetPath`

Retrieves the coordinates defining the endpoints of lines and the control points of curves found in the path that is selected into the device context.

```
int GetPath(
    LPPOINT lpPoints,
    LPBYTE lpTypes,
    int nCount) const;
```

### Parameters

*`lpPoints`*\
Points to an array of [`POINT`](/windows/win32/api/windef/ns-windef-point) data structures or `CPoint` objects where the line endpoints and curve control points are placed.

*`lpTypes`*\
Points to an array of bytes where the vertex types are placed. Values are one of the following:

- `PT_MOVETO` Specifies that the corresponding point in *`lpPoints`* starts a disjoint figure.

- `PT_LINETO` Specifies that the previous point and the corresponding point in *`lpPoints`* are the endpoints of a line.

- `PT_BEZIERTO` Specifies that the corresponding point in *`lpPoints`* is a control point or ending point for a Bzier curve.

`PT_BEZIERTO` types always occur in sets of three. The point in the path immediately preceding them defines the starting point for the Bzier curve. The first two `PT_BEZIERTO` points are the control points, and the third `PT_BEZIERTO` point is the end point (if hard-coded).

   A `PT_LINETO` or `PT_BEZIERTO` type may be combined with the following flag (by using the bitwise operator **OR**) to indicate that the corresponding point is the last point in a figure and that the figure should be closed:

- `PT_CLOSEFIGURE` Specifies that the figure is automatically closed after the corresponding line or curve is drawn. The figure is closed by drawing a line from the line or curve endpoint to the point corresponding to the last `PT_MOVETO`.

*`nCount`*\
Specifies the total number of [`POINT`](/windows/win32/api/windef/ns-windef-point) data structures that may be placed in the *`lpPoints`* array. This value must be the same as the number of bytes that may be placed in the *`lpTypes`* array.

### Return Value

If the *`nCount`* parameter is nonzero, the number of points enumerated. If *`nCount`* is 0, the total number of points in the path (and `GetPath` writes nothing to the buffers). If *`nCount`* is nonzero and is less than the number of points in the path, the return value is -1.

### Remarks

The device context must contain a closed path. The points of the path are returned in logical coordinates. Points are stored in the path in device coordinates, so `GetPath` changes the points from device coordinates to logical coordinates by using the inverse of the current transformation. The `FlattenPath` member function may be called before `GetPath`, to convert all curves in the path into line segments.

### Example

  See the example for [`CDC::BeginPath`](#beginpath).

## <a name="getpixel"></a> `CDC::GetPixel`

Retrieves the RGB color value of the pixel at the point specified by *`x`* and *`y`*.

```
COLORREF GetPixel(
    int x,
    int y) const;

COLORREF GetPixel(POINT point) const;
```

### Parameters

*`x`*\
Specifies the logical x-coordinate of the point to be examined.

*`y`*\
Specifies the logical y-coordinate of the point to be examined.

*`point`*\
Specifies the logical x- and y-coordinates of the point to be examined.

### Return Value

For either version of the function, an RGB color value for the color of the given point. It's -1 if the coordinates don't specify a point in the clipping region.

### Remarks

The point must be in the clipping region. If the point isn't in the clipping region, the function has no effect and returns -1.

Not all devices support the `GetPixel` function. For more information, see the `RC_BITBLT` raster capability under the [`GetDeviceCaps`](#getdevicecaps) member function.

The `GetPixel` member function has two forms. The first takes two coordinate values; the second takes either a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object.

## <a name="getpolyfillmode"></a> `CDC::GetPolyFillMode`

Retrieves the current polygon-filling mode.

```
int GetPolyFillMode() const;
```

### Return Value

The current polygon-filled mode, `ALTERNATE` or `WINDING`, if the function is successful.

### Remarks

See the `SetPolyFillMode` member function for a description of the polygon-filling modes.

## <a name="getrop2"></a> `CDC::GetROP2`

Retrieves the current drawing mode.

```
int GetROP2() const;
```

### Return Value

The drawing mode. For a list of the drawing mode values, see the `SetROP2` member function.

### Remarks

The drawing mode specifies how the colors of the pen and the interior of filled objects are combined with the color already on the display surface.

## <a name="getsafehdc"></a> `CDC::GetSafeHdc`

Call this member function to get [`m_hDC`](#m_hdc), the output device context.

```
HDC GetSafeHdc() const;
```

### Return Value

A device context handle.

### Remarks

This member function also works with null pointers.

## <a name="getstretchbltmode"></a> `CDC::GetStretchBltMode`

Retrieves the current bitmap-stretching mode.

```
int GetStretchBltMode() const;
```

### Return Value

The return value specifies the current bitmap-stretching mode — `STRETCH_ANDSCANS`, `STRETCH_DELETESCANS`, or `STRETCH_ORSCANS` — if the function is successful.

### Remarks

The bitmap-stretching mode defines how information is removed from bitmaps that are stretched or compressed by the `StretchBlt` member function.

The `STRETCH_ANDSCANS` and `STRETCH_ORSCANS` modes are typically used to preserve foreground pixels in monochrome bitmaps. The `STRETCH_DELETESCANS` mode is typically used to preserve color in color bitmaps.

## <a name="gettabbedtextextent"></a> `CDC::GetTabbedTextExtent`

Call this member function to compute the width and height of a character string using [`m_hAttribDC`](#m_hattribdc), the attribute device context.

```
CSize GetTabbedTextExtent(
    LPCTSTR lpszString,
    int nCount,
    int nTabPositions,
    LPINT lpnTabStopPositions) const;

CSize GetTabbedTextExtent(
    const CString& str,
    int nTabPositions,
    LPINT lpnTabStopPositions) const;
```

### Parameters

*`lpszString`*\
Points to a character string. You can also pass a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object for this parameter.

*`nCount`*\
Specifies the [length of the string](/windows/win32/gdi/specifying-length-of-text-output-string) pointed to by *`lpszString`*.

*`nTabPositions`*\
Specifies the number of tab-stop positions in the array pointed to by *`lpnTabStopPositions`*.

*`lpnTabStopPositions`*\
Points to an array of integers containing the tab-stop positions in logical units. The tab stops must be sorted in increasing order; the smallest x-value should be the first item in the array. Back tabs aren't allowed.

*`str`*\
A `CString` object that contains the specified characters to be drawn.

### Return Value

The dimensions of the string (in logical units) in a [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object.

### Remarks

If the string contains one or more tab characters, the width of the string is based upon the tab stops specified by *`lpnTabStopPositions`*. The function uses the currently selected font to compute the dimensions of the string.

The current clipping region doesn't offset the width and height returned by the `GetTabbedTextExtent` function.

Since some devices don't place characters in regular cell arrays (that is, they kern the characters), the sum of the extents of the characters in a string may not be equal to the extent of the string.

If *`nTabPositions`* is 0 and *`lpnTabStopPositions`* is `NULL`, tabs are expanded to eight times the average character width. If *`nTabPositions`* is 1, the tab stops will be separated by the distance specified by the first value in the array to which *`lpnTabStopPositions`* points. If *`lpnTabStopPositions`* points to more than a single value, a tab stop is set for each value in the array, up to the number specified by *`nTabPositions`*.

## <a name="gettextalign"></a> `CDC::GetTextAlign`

Retrieves the status of the text-alignment flags for the device context.

```
UINT GetTextAlign() const;
```

### Return Value

The status of the text-alignment flags. The return value is one or more of the following values:

- `TA_BASELINE` Specifies alignment of the x-axis and the baseline of the chosen font within the bounding rectangle.

- `TA_BOTTOM` Specifies alignment of the x-axis and the bottom of the bounding rectangle.

- `TA_CENTER` Specifies alignment of the y-axis and the center of the bounding rectangle.

- `TA_LEFT` Specifies alignment of the y-axis and the left side of the bounding rectangle.

- `TA_NOUPDATECP` Specifies that the current position isn't updated.

- `TA_RIGHT` Specifies alignment of the y-axis and the right side of the bounding rectangle.

- `TA_TOP` Specifies alignment of the x-axis and the top of the bounding rectangle.

- `TA_UPDATECP` Specifies that the current position is updated.

### Remarks

The text-alignment flags determine how the `TextOut` and `ExtTextOut` member functions align a string of text in relation to the string's starting point. The text-alignment flags aren't necessarily single-bit flags and may be equal to 0. To test whether a flag is set, an application should follow these steps:

1. Apply the bitwise **OR** (`|`) operator to the flag and its related flags, grouped as follows:

   - `TA_LEFT`, `TA_CENTER`, and `TA_RIGHT`

   - `TA_BASELINE`, `TA_BOTTOM`, and `TA_TOP`

   - `TA_NOUPDATECP` and `TA_UPDATECP`

1. Apply the C++ bitwise **AND** (`&`) operator to the result and the return value of `GetTextAlign`.

1. Test for the equality of this result and the flag.

## <a name="gettextcharacterextra"></a> `CDC::GetTextCharacterExtra`

Retrieves the current setting for the amount of intercharacter spacing.

```
int GetTextCharacterExtra() const;
```

### Return Value

The amount of the intercharacter spacing.

### Remarks

GDI adds this spacing to each character, including break characters, when it writes a line of text to the device context.

The default value for the amount of intercharacter spacing is 0.

## <a name="gettextcolor"></a> `CDC::GetTextColor`

Retrieves the current text color.

```
COLORREF GetTextColor() const;
```

### Return Value

The current text color as an RGB color value.

### Remarks

The text color is the foreground color of characters drawn by using the GDI text-output member functions [`TextOut`](#textout), [`ExtTextOut`](#exttextout), and [`TabbedTextOut`](#tabbedtextout).

## <a name="gettextextent"></a> `CDC::GetTextExtent`

Call this member function to compute the width and height of a line of text using the current font to determine the dimensions.

```
CSize GetTextExtent(
    LPCTSTR lpszString,
    int nCount) const;

CSize GetTextExtent(const CString& str) const;
```

### Parameters

*`lpszString`*\
Points to a string of characters. You can also pass a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object for this parameter.

*`nCount`*\
Specifies the number of characters in the string.

*`str`*\
A `CString` object that contains the specified characters.

### Return Value

The dimensions of the string (in logical units) in a [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object.

### Remarks

The information is retrieved from [`m_hAttribDC`](#m_hattribdc), the attribute device context.

By default, `GetTextExtent` assumes the text for which it retrieves the dimension is set along a horizontal line (that is, the escapement is 0). If you create a font specifying a non-zero escapement, you must convert the angle of the text explicitly to get the dimensions of the string.

The current clipping region doesn't affect the width and height returned by `GetTextExtent`.

Since some devices don't place characters in regular cell arrays (that is, they carry out kerning), the sum of the extents of the characters in a string may not be equal to the extent of the string.

## <a name="gettextextentexpointi"></a> `CDC::GetTextExtentExPointI`

Retrieves the number of characters in a specified string that will fit within a specified space and fills an array with the text extent for each of those characters.

```
BOOL GetTextExtentExPointI(
    LPWORD pgiIn,
    int cgi,
    int nMaxExtent,
    LPINT lpnFit,
    LPINT alpDx,
    LPSIZE lpSize) const;
```

### Parameters

*`pgiIn`*\
A pointer to an array of glyph indices for which extents are to be retrieved.

*`cgi`*\
Specifies the number of glyphs in the array pointed to by *`pgiIn`*.

*`nMaxExtent`*\
Specifies the maximum allowable width, in logical units, of the formatted string.

*`lpnFit`*\
A pointer to an integer that receives a count of the maximum number of characters that will fit in the space specified by *`nMaxExtent`*. When *`lpnFit`* is `NULL`, *`nMaxExtent`* is ignored.

*`alpDx`*\
A pointer to an array of integers that receives partial glyph extents. Each element in the array gives the distance, in logical units, between the beginning of the glyph indices array and one of the glyphs that fits in the space specified by *`nMaxExtent`*. Although this array should have at least as many elements as glyph indices specified by *`cgi`*, the function fills the array with extents only for as many glyph indices as are specified by *`lpnFit`*. If *`lpnDx`* is `NULL`, the function doesn't compute partial string widths.

*`lpSize`*\
Pointer to a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure that receives the dimensions of the glyph indices array, in logical units. This value cannot be `NULL`.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

This member function emulates the functionality of the function [`GetTextExtentExPointI`](/windows/win32/api/wingdi/nf-wingdi-gettextextentexpointi), as described in the Windows SDK.

## <a name="gettextextentpointi"></a> `CDC::GetTextExtentPointI`

Retrieves the width and height of the specified array of glyph indices.

```
BOOL GetTextExtentPointI(
    LPWORD pgiIn,
    int cgi,
    LPSIZE lpSize) const;
```

### Parameters

*`pgiIn`*\
A pointer to an array of glyph indices for which extents are to be retrieved.

*`cgi`*\
Specifies the number of glyphs in the array pointed to by *`pgiIn`*.

*`lpSize`*\
Pointer to a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure that receives the dimensions of the glyph indices array, in logical units. This value cannot be `NULL`.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

This member function emulates the functionality of the function [`GetTextExtentPointI`](/windows/win32/api/wingdi/nf-wingdi-gettextextentpointi), as described in the Windows SDK.

## <a name="gettextface"></a> `CDC::GetTextFace`

Call this member function to copy the typeface name of the current font into a buffer.

```
int GetTextFace(
    int nCount,
    LPTSTR lpszFacename) const;

int GetTextFace(CString& rString) const;
```

### Parameters

*`nCount`*\
Specifies the size of the buffer (in bytes). If the typeface name is longer than the number of bytes specified by this parameter, the name is truncated.

*`lpszFacename`*\
Points to the buffer for the typeface name.

*`rString`*\
A reference to a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object.

### Return Value

The number of bytes copied to the buffer, not including the terminating null character. It's 0 if an error occurs.

### Remarks

The typeface name is copied as a null-terminated string.

## <a name="gettextmetrics"></a> `CDC::GetTextMetrics`

Retrieves the metrics for the current font using the attribute device context.

```
BOOL GetTextMetrics(LPTEXTMETRIC lpMetrics) const;
```

### Parameters

*`lpMetrics`*\
Points to the [`TEXTMETRIC`](/windows/win32/api/wingdi/ns-wingdi-textmetricw) structure that receives the metrics.

### Return Value

Nonzero if the function is successful; otherwise 0.

## <a name="getviewportext"></a> `CDC::GetViewportExt`

Retrieves the x- and y-extents of the device context's viewport.

```
CSize GetViewportExt() const;
```

### Return Value

The x- and y-extents (in device units) as a `CSize` object.

## <a name="getviewportorg"></a> `CDC::GetViewportOrg`

Retrieves the x- and y-coordinates of the origin of the viewport associated with the device context.

```
CPoint GetViewportOrg() const;
```

### Return Value

The origin of the viewport (in device coordinates) as a `CPoint` object.

## <a name="getwindow"></a> `CDC::GetWindow`

Returns the window associated with the display device context.

```
CWnd* GetWindow() const;
```

### Return Value

Pointer to a `CWnd` object if successful; otherwise `NULL`.

### Remarks

This is an advanced function. For example, this member function may not return the view window when printing or in print preview. It always returns the window associated with output. Output functions that use the given DC draw into this window.

## <a name="getwindowext"></a> `CDC::GetWindowExt`

Retrieves the x- and y-extents of the window associated with the device context.

```
CSize GetWindowExt() const;
```

### Return Value

The x- and y-extents (in logical units) as a `CSize` object.

## <a name="getwindoworg"></a> `CDC::GetWindowOrg`

Retrieves the x- and y-coordinates of the origin of the window associated with the device context.

```
CPoint GetWindowOrg() const;
```

### Return Value

The origin of the window (in logical coordinates) as a `CPoint` object.

## <a name="getworldtransform"></a> `CDC::GetWorldTransform`

Retrieves the current world-space to page-space transformation.

```
BOOL GetWorldTransform(XFORM& rXform) const;
```

### Parameters

*`rXform`*\
Reference to an [`XFORM`](/windows/win32/api/wingdi/ns-wingdi-xform) structure that receives the current world-space to page-space transformation.

### Return Value

Returns a nonzero value on success.

Returns 0 on failure.

To get extended error information, call [`GetLastError`](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror).

### Remarks

This method wraps the Windows GDI function [`GetWorldTransform`](/windows/win32/api/wingdi/nf-wingdi-getworldtransform).

## <a name="gradientfill"></a> `CDC::GradientFill`

Call this member function to fill rectangle and triangle structures with color that smoothly fades from one side to the other.

```
BOOL GradientFill(
    TRIVERTEX* pVertices,
    ULONG nVertices,
    void* pMesh,
    ULONG nMeshElements,
    DWORD dwMode);
```

### Parameters

*`pVertices`*\
Pointer to an array of [`TRIVERTEX`](/windows/win32/api/wingdi/ns-wingdi-trivertex) structures that each define a triangle vertex.

*`nVertices`*\
The number of vertices.

*`pMesh`*\
Array of [`GRADIENT_TRIANGLE`](/windows/win32/api/wingdi/ns-wingdi-gradient_triangle) structures in triangle mode, or an array of [`GRADIENT_RECT`](/windows/win32/api/wingdi/ns-wingdi-gradient_rect) structures in rectangle mode.

*`nMeshElements`*\
The number of elements (triangles or rectangles) in *`pMesh`*.

*`dwMode`*\
Specifies gradient fill mode. For a list of possible values, see [`GradientFill`](/windows/win32/api/wingdi/nf-wingdi-gradientfill) in the Windows SDK.

### Return Value

`TRUE` if successful; otherwise `FALSE`.

### Remarks

For more information, see `GradientFill` in the Windows SDK.

## <a name="graystring"></a> `CDC::GrayString`

Draws dimmed (gray) text at the given location by writing the text in a memory bitmap, dimming the bitmap, and then copying the bitmap to the display.

```
virtual BOOL GrayString(
    CBrush* pBrush,
    BOOL (CALLBACK* lpfnOutput)(
    HDC,
    LPARAM,
    int),
    LPARAM lpData,
    int nCount,
    int x,
    int y,
    int nWidth,
    int nHeight);
```

### Parameters

*`pBrush`*\
Identifies the brush to be used for dimming (graying).

*`lpfnOutput`*\
Specifies the procedure-instance address of the application-supplied callback function that will draw the string. For more information, see the description of the Windows `OutputFunc` [callback function](callback-functions-used-by-mfc.md#graystring). If this parameter is `NULL`, the system uses the Windows `TextOut` function to draw the string, and *`lpData`* is assumed to be a long pointer to the character string to be output.

*`lpData`*\
Specifies a far pointer to data to be passed to the output function. If *`lpfnOutput`* is `NULL`, *`lpData`* must be a long pointer to the string to be output.

*`nCount`*\
Specifies the number of characters to be output. If this parameter is 0, `GrayString` calculates the length of the string (assuming that *`lpData`* is a pointer to the string). If *`nCount`* is 1 and the function pointed to by *`lpfnOutput`* returns 0, the image is shown but not dimmed.

*`x`*\
Specifies the logical x-coordinate of the starting position of the rectangle that encloses the string.

*`y`*\
Specifies the logical y-coordinate of the starting position of the rectangle that encloses the string.

*`nWidth`*\
Specifies the width (in logical units) of the rectangle that encloses the string. If *`nWidth`* is 0, `GrayString` calculates the width of the area, assuming *`lpData`* is a pointer to the string.

*`nHeight`*\
Specifies the height (in logical units) of the rectangle that encloses the string. If *`nHeight`* is 0, `GrayString` calculates the height of the area, assuming *`lpData`* is a pointer to the string.

### Return Value

Nonzero if the string is drawn, or 0 if either the `TextOut` function or the application-supplied output function returned 0, or if there was insufficient memory to create a memory bitmap for dimming.

### Remarks

The function dims the text regardless of the selected brush and background. The `GrayString` member function uses the currently selected font. The `MM_TEXT` mapping mode must be selected before using this function.

An application can draw dimmed (grayed) strings on devices that support a solid gray color without calling the `GrayString` member function. The system color `COLOR_GRAYTEXT` is the solid-gray system color used to draw disabled text. The application can call the `GetSysColor` Windows function to retrieve the color value of `COLOR_GRAYTEXT`. If the color is other than 0 (black), the application can call the `SetTextColor` member function to set the text color to the color value, and then draw the string directly. If the retrieved color is black, the application must call `GrayString` to dim (gray) the text.

If *`lpfnOutput`* is `NULL`, GDI uses the Windows [`TextOut`](/windows/win32/api/wingdi/nf-wingdi-textoutw) function, and *`lpData`* is assumed to be a far pointer to the character to be output. If the characters to be output cannot be handled by the `TextOut` member function (for example, the string is stored as a bitmap), the application must supply its own output function.

All callback functions must trap Microsoft Foundation exceptions before returning to Windows, since exceptions cannot be thrown across callback boundaries. For more information about exceptions, see the article [Exceptions](../../mfc/exception-handling-in-mfc.md).

The callback function passed to `GrayString` must use the **`__stdcall`** calling convention and must be exported with **`__declspec`**.

When the framework is in preview mode, a call to the `GrayString` member function is translated to a `TextOut` call, and the callback function isn't called.

## <a name="himetrictodp"></a> `CDC::HIMETRICtoDP`

Use this function when you convert `HIMETRIC` sizes from OLE to pixels.

```cpp
void HIMETRICtoDP(LPSIZE lpSize) const;
```

### Parameters

*`lpSize`*\
Points to a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object.

### Remarks

If the mapping mode of the device context object is `MM_LOENGLISH`, `MM_HIENGLISH`, `MM_LOMETRIC` or `MM_HIMETRIC`, then the conversion is based on the number of pixels in the physical inch. If the mapping mode is one of the other non-constrained modes (for example, `MM_TEXT`), then the conversion is based on the number of pixels in the logical inch.

## <a name="himetrictolp"></a> `CDC::HIMETRICtoLP`

Call this function to convert `HIMETRIC` units into logical units.

```cpp
void HIMETRICtoLP(LPSIZE lpSize) const;
```

### Parameters

*`lpSize`*\
Points to a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object.

### Remarks

Use this function when you get `HIMETRIC` sizes from OLE and wish to convert them to your application's natural mapping mode.

The conversion is accomplished by first converting the `HIMETRIC` units into pixels and then converting these units into logical units using the device context's current mapping units. Note that the extents of the device's window and viewport will affect the result.

## <a name="intersectcliprect"></a> `CDC::IntersectClipRect`

Creates a new clipping region by forming the intersection of the current region and the rectangle specified by *`x1`*, *`y1`*, *`x2`*, and *`y2`*.

```
int IntersectClipRect(
    int x1,
    int y1,
    int x2,
    int y2);

int IntersectClipRect(LPCRECT lpRect);
```

### Parameters

*`x1`*\
Specifies the logical x-coordinate of the upper-left corner of the rectangle.

*`y1`*\
Specifies the logical y-coordinate of the upper-left corner of the rectangle.

*`x2`*\
Specifies the logical x-coordinate of the lower-right corner of the rectangle.

*`y2`*\
Specifies the logical y-coordinate of the lower-right corner of the rectangle.

*`lpRect`*\
Specifies the rectangle. You can pass either a `CRect` object or a pointer to a `RECT` structure for this parameter.

### Return Value

The new clipping region's type. It can be any one of the following values:

- `COMPLEXREGION` New clipping region has overlapping borders.

- `ERROR` Device context isn't valid.

- `NULLREGION` New clipping region is empty.

- `SIMPLEREGION` New clipping region has no overlapping borders.

### Remarks

GDI clips all subsequent output to fit within the new boundary. The width and height must not exceed 32,767.

## <a name="invertrect"></a> `CDC::InvertRect`

Inverts the contents of the given rectangle.

```cpp
void InvertRect(LPCRECT lpRect);
```

### Parameters

*`lpRect`*\
Points to a `RECT` that contains the logical coordinates of the rectangle to be inverted. You can also pass a `CRect` object for this parameter.

### Remarks

Inversion is a logical NOT operation and flips the bits of each pixel. On monochrome displays, the function makes white pixels black and black pixels white. On color displays, the inversion depends on how colors are generated for the display. Calling `InvertRect` twice with the same rectangle restores the display to its previous colors.

If the rectangle is empty, nothing is drawn.

### Example

[!code-cpp[NVC_MFCDocView#36](../../mfc/codesnippet/cpp/cdc-class_8.cpp)]

## <a name="invertrgn"></a> `CDC::InvertRgn`

Inverts the colors in the region specified by *`pRgn`*.

```
BOOL InvertRgn(CRgn* pRgn);
```

### Parameters

*`pRgn`*\
Identifies the region to be inverted. The coordinates for the region are specified in logical units.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

On monochrome displays, the function makes white pixels black and black pixels white. On color displays, the inversion depends on how the colors are generated for the display.

## <a name="isprinting"></a> `CDC::IsPrinting`

Determines whether the device context is being used for printing.

```
BOOL IsPrinting() const;
```

### Return Value

Nonzero if the `CDC` object is a printer DC; otherwise 0.

## <a name="lineto"></a> `CDC::LineTo`

Draws a line from the current position up to, but not including, the point specified by *`x`* and *`y`* (or *`point`*).

```
BOOL LineTo(
    int x,
    int y);

BOOL LineTo(POINT point);
```

### Parameters

*`x`*\
Specifies the logical x-coordinate of the endpoint for the line.

*`y`*\
Specifies the logical y-coordinate of the endpoint for the line.

*`point`*\
Specifies the endpoint for the line. You can pass either a `POINT` structure or a `CPoint` object for this parameter.

### Return Value

Nonzero if the line is drawn; otherwise 0.

### Remarks

The line is drawn with the selected pen. The current position is set to *`x`*, *`y`* or to *`point`*.

### Example

  See the example for [`CRect::CenterPoint`](../../atl-mfc-shared/reference/crect-class.md#centerpoint).

## <a name="lptodp"></a> `CDC::LPtoDP`

Converts logical units into device units.

```cpp
void LPtoDP(
    LPPOINT lpPoints,
    int nCount = 1) const;

void LPtoDP(LPRECT lpRect) const;
void LPtoDP(LPSIZE lpSize) const;
```

### Parameters

*`lpPoints`*\
Points to an array of points. Each point in the array is a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object.

*`nCount`*\
The number of points in the array.

*`lpRect`*\
Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object. This parameter is used for the common case of mapping a rectangle from logical to device units.

*`lpSize`*\
Points to a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or a [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object.

### Remarks

The function maps the coordinates of each point, or dimensions of a size, from GDI's logical coordinate system into a device coordinate system. The conversion depends on the current mapping mode and the settings of the origins and extents of the device's window and viewport.

The x- and y-coordinates of points are 2-byte signed integers in the range -32,768 through 32,767. In cases where the mapping mode would result in values larger than these limits, the system sets the values to -32,768 and 32,767, respectively.

## <a name="lptohimetric"></a> `CDC::LPtoHIMETRIC`

Call this function to convert logical units into `HIMETRIC` units.

```cpp
void LPtoHIMETRIC(LPSIZE lpSize) const;
```

### Parameters

*`lpSize`*\
Points to a `SIZE` structure or a `CSize` object.

### Remarks

Use this function when you give `HIMETRIC` sizes to OLE, converting from your application's natural mapping mode. The extents of the device's window and viewport will affect the result.

The conversion is accomplished by first converting the logical units into pixels using the device context's current mapping units and then converting these units into `HIMETRIC` units.

## <a name="m_hattribdc"></a> `CDC::m_hAttribDC`

The attribute device context for this `CDC` object.

```
HDC m_hAttribDC;
```

### Remarks

By default, this device context is equal to `m_hDC`. In general, `CDC` GDI calls that request information from the device context are directed to `m_hAttribDC`. See the [`CDC`](../../mfc/reference/cdc-class.md) class description for more on the use of these two device contexts.

## <a name="m_hdc"></a> `CDC::m_hDC`

The output device context for this `CDC` object.

```
HDC m_hDC;
```

### Remarks

By default, `m_hDC` is equal to `m_hAttribDC`, the other device context wrapped by `CDC`. In general, `CDC` GDI calls that create output go to the `m_hDC` device context. You can initialize `m_hDC` and `m_hAttribDC` to point to different devices. See the [`CDC`](../../mfc/reference/cdc-class.md) class description for more on the use of these two device contexts.

## <a name="maskblt"></a> `CDC::MaskBlt`

Combines the color data for the source and destination bitmaps using the given mask and raster operation.

```
BOOL MaskBlt(
    int x,
    int y,
    int nWidth,
    int nHeight,
    CDC* pSrcDC,
    int xSrc,
    int ySrc,
    CBitmap& maskBitmap,
    int xMask,
    int yMask,
    DWORD dwRop);
```

### Parameters

*`x`*\
Specifies the logical x-coordinate of the upper-left corner of the destination rectangle.

*`y`*\
Specifies the logical y-coordinate of the upper-left corner of the destination rectangle.

*`nWidth`*\
Specifies the width, in logical units, of the destination rectangle and source bitmap.

*`nHeight`*\
Specifies the height, in logical units, of the destination rectangle and source bitmap.

*`pSrcDC`*\
Identifies the device context from which the bitmap is to be copied. It must be zero if the *`dwRop`* parameter specifies a raster operation that doesn't include a source.

*`xSrc`*\
Specifies the logical x-coordinate of the upper-left corner of the source bitmap.

*`ySrc`*\
Specifies the logical y-coordinate of the upper-left corner of the source bitmap.

*`maskBitmap`*\
Identifies the monochrome mask bitmap combined with the color bitmap in the source device context.

*`xMask`*\
Specifies the horizontal pixel offset for the mask bitmap specified by the *`maskBitmap`* parameter.

*`yMask`*\
Specifies the vertical pixel offset for the mask bitmap specified by the *`maskBitmap`* parameter.

*`dwRop`*\
Specifies both foreground and background ternary raster operation codes, which the function uses to control the combination of source and destination data. The background raster operation code is stored in the high byte of the high word of this value; the foreground raster operation code is stored in the low byte of the high word of this value; the low word of this value is ignored, and should be zero. The macro `MAKEROP4` creates such combinations of foreground and background raster operation codes. See the Remarks section for a discussion of foreground and background in the context of this function. See the `BitBlt` member function for a list of common raster operation codes.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

A value of 1 in the mask specified by *`maskBitmap`* indicates that the foreground raster operation code specified by *`dwRop`* should be applied at that location. A value of 0 in the mask indicates that the background raster operation code specified by *`dwRop`* should be applied at that location. If the raster operations require a source, the mask rectangle must cover the source rectangle. If it doesn't, the function fails. If the raster operations don't require a source, the mask rectangle must cover the destination rectangle. If it doesn't, the function fails.

If a rotation or shear transformation is in effect for the source device context when this function is called, an error occurs. However, other types of transformations are allowed.

If the color formats of the source, pattern, and destination bitmaps differ, this function converts the pattern or source format, or both, to match the destination format. If the mask bitmap isn't a monochrome bitmap, an error occurs. When an enhanced metafile is being recorded, an error occurs (and the function returns 0) if the source device context identifies an enhanced-metafile device context. Not all devices support `MaskBlt`. An application should call `GetDeviceCaps` to determine whether a device supports this function. If no mask bitmap is supplied, this function behaves exactly like `BitBlt`, using the foreground raster operation code. The pixel offsets in the mask bitmap map to the point (0,0) in the source device context's bitmap. This is useful for cases in which a mask bitmap contains a set of masks; an application can easily apply any one of them to a mask-blitting task by adjusting the pixel offsets and rectangle sizes sent to `MaskBlt`.

## <a name="modifyworldtransform"></a> `CDC::ModifyWorldTransform`

Changes the world transformation for a device context using the specified mode.

```
BOOL ModifyWorldTransform(
    const XFORM& rXform,
    DWORD iMode);
```

### Parameters

*`rXform`*\
Reference to an [`XFORM`](/windows/win32/api/wingdi/ns-wingdi-xform) structure used to modify the world transformation for the given device context.

*`iMode`*\
Specifies how the transformation data modifies the current world transformation. For a list of the values that this parameter can take, see [`ModifyWorldTransform`](/windows/win32/api/wingdi/nf-wingdi-modifyworldtransform).

### Return Value

Returns a nonzero value on success.

Returns 0 on failure.

To get extended error information, call [`GetLastError`](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror).

### Remarks

This method wraps the Windows GDI function [`ModifyWorldTransform`](/windows/win32/api/wingdi/nf-wingdi-modifyworldtransform).

## <a name="moveto"></a> `CDC::MoveTo`

Moves the current position to the point specified by *`x`* and *`y`* (or by *`point`*).

```
CPoint MoveTo(
    int x,
    int y);

CPoint MoveTo(POINT point);
```

### Parameters

*`x`*\
Specifies the logical x-coordinate of the new position.

*`y`*\
Specifies the logical y-coordinate of the new position.

*`point`*\
Specifies the new position. You can pass either a `POINT` structure or a `CPoint` object for this parameter.

### Return Value

The x- and y-coordinates of the previous position as a `CPoint` object.

### Example

  See the example for [`CRect::CenterPoint`](../../atl-mfc-shared/reference/crect-class.md#centerpoint).

## <a name="offsetcliprgn"></a> `CDC::OffsetClipRgn`

Moves the clipping region of the device context by the specified offsets.

```
int OffsetClipRgn(
    int x,
    int y);

int OffsetClipRgn(SIZE size);
```

### Parameters

*`x`*\
Specifies the number of logical units to move left or right.

*`y`*\
Specifies the number of logical units to move up or down.

*`size`*\
Specifies the amount to offset.

### Return Value

The new region's type. It can be any one of the following values:

- `COMPLEXREGION` Clipping region has overlapping borders.

- `ERROR` Device context isn't valid.

- `NULLREGION` Clipping region is empty.

- `SIMPLEREGION` Clipping region has no overlapping borders.

### Remarks

The function moves the region *`x`* units along the x-axis and *`y`* units along the y-axis.

## <a name="offsetviewportorg"></a> `CDC::OffsetViewportOrg`

Modifies the coordinates of the viewport origin relative to the coordinates of the current viewport origin.

```
virtual CPoint OffsetViewportOrg(
    int nWidth,
    int nHeight);
```

### Parameters

*`nWidth`*\
Specifies the number of device units to add to the current origin's x-coordinate.

*`nHeight`*\
Specifies the number of device units to add to the current origin's y-coordinate.

### Return Value

The previous viewport origin (in device coordinates) as a `CPoint` object.

## <a name="offsetwindoworg"></a> `CDC::OffsetWindowOrg`

Modifies the coordinates of the window origin relative to the coordinates of the current window origin.

```
CPoint OffsetWindowOrg(
    int nWidth,
    int nHeight);
```

### Parameters

*`nWidth`*\
Specifies the number of logical units to add to the current origin's x-coordinate.

*`nHeight`*\
Specifies the number of logical units to add to the current origin's y-coordinate.

### Return Value

The previous window origin (in logical coordinates) as a `CPoint` object.

## <a name="operator_hdc"></a> `CDC::operator HDC`

Use this operator to retrieve the device context handle of the `CDC` object.

```
operator HDC() const;
```

### Return Value

If successful, the handle of the device context object; otherwise, `NULL`.

### Remarks

You can use the handle to call Windows APIs directly.

## <a name="paintrgn"></a> `CDC::PaintRgn`

Fills the region specified by *`pRgn`* using the current brush.

```
BOOL PaintRgn(CRgn* pRgn);
```

### Parameters

*`pRgn`*\
Identifies the region to be filled. The coordinates for the given region are specified in logical units.

### Return Value

Nonzero if the function is successful; otherwise 0.

## <a name="patblt"></a> `CDC::PatBlt`

Creates a bit pattern on the device.

```
BOOL PatBlt(
    int x,
    int y,
    int nWidth,
    int nHeight,
    DWORD dwRop);
```

### Parameters

*`x`*\
Specifies the logical x-coordinate of the upper-left corner of the rectangle that is to receive the pattern.

*`y`*\
Specifies the logical y-coordinate of the upper-left corner of the rectangle that is to receive the pattern.

*`nWidth`*\
Specifies the width (in logical units) of the rectangle that is to receive the pattern.

*`nHeight`*\
Specifies the height (in logical units) of the rectangle that is to receive the pattern.

*`dwRop`*\
Specifies the raster-operation code. Raster-operation codes (ROPs) define how GDI combines colors in output operations that involve a current brush, a possible source bitmap, and a destination bitmap. This parameter can be one of the following values:

- `PATCOPY` Copies pattern to destination bitmap.

- `PATINVERT` Combines destination bitmap with pattern using the Boolean **XOR** (`^`) operator.

- `DSTINVERT` Inverts the destination bitmap.

- `BLACKNESS` Turns all output black.

- `WHITENESS` Turns all output white.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The pattern is a combination of the selected brush and the pattern already on the device. The raster-operation code specified by *`dwRop`* defines how the patterns are to be combined. The raster operations listed for this function are a limited subset of the full 256 ternary raster-operation codes; in particular, a raster-operation code that refers to a source cannot be used.

Not all device contexts support the `PatBlt` function. To determine whether a device context supports `PatBlt`, call the `GetDeviceCaps` member function with the `RASTERCAPS` index and check the return value for the `RC_BITBLT` flag.

## <a name="pie"></a> `CDC::Pie`

Draws a pie-shaped wedge by drawing an elliptical arc whose center and two endpoints are joined by lines.

```
BOOL Pie(
    int x1,
    int y1,
    int x2,
    int y2,
    int x3,
    int y3,
    int x4,
    int y4);

BOOL Pie(
    LPCRECT lpRect,
    POINT ptStart,
    POINT ptEnd);
```

### Parameters

*`x1`*\
Specifies the x-coordinate of the upper-left corner of the bounding rectangle (in logical units).

*`y1`*\
Specifies the y-coordinate of the upper-left corner of the bounding rectangle (in logical units).

*`x2`*\
Specifies the x-coordinate of the lower-right corner of the bounding rectangle (in logical units).

*`y2`*\
Specifies the y-coordinate of the lower-right corner of the bounding rectangle (in logical units).

*`x3`*\
Specifies the x-coordinate of the arc's starting point (in logical units). This point doesn't have to lie exactly on the arc.

*`y3`*\
Specifies the y-coordinate of the arc's starting point (in logical units). This point doesn't have to lie exactly on the arc.

*`x4`*\
Specifies the x-coordinate of the arc's endpoint (in logical units). This point doesn't have to lie exactly on the arc.

*`y4`*\
Specifies the y-coordinate of the arc's endpoint (in logical units). This point doesn't have to lie exactly on the arc.

*`lpRect`*\
Specifies the bounding rectangle. You can pass either a `CRect` object or a pointer to a `RECT` structure for this parameter.

*`ptStart`*\
Specifies the starting point of the arc. This point doesn't have to lie exactly on the arc. You can pass either a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object for this parameter.

*`ptEnd`*\
Specifies the endpoint of the arc. This point doesn't have to lie exactly on the arc. You can pass either a `POINT` structure or a `CPoint` object for this parameter.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The center of the arc is the center of the bounding rectangle specified by *`x1`*, *`y1`*, *`x2`*, and *`y2`* (or by *`lpRect`*). The starting and ending points of the arc are specified by *`x3`*, *`y3`*, *`x4`*, and *`y4`* (or by *`ptStart`* and *`ptEnd`*).

The arc is drawn with the selected pen, moving in a counterclockwise direction. Two more lines are drawn from each endpoint to the arc's center. The pie-shaped area is filled with the current brush. If *`x3`* equals *`x4`* and *`y3`* equals *`y4`*, the result is an ellipse with a single line from the center of the ellipse to the point (*`x3`*, *`y3`*) or (*`x4`*, *`y4`*).

The figure drawn by this function extends up to but doesn't include the right and bottom coordinates. This means that the height of the figure is *`y2`* - *`y1`* and the width of the figure is *`x2`* - *`x1`*. Both the width and the height of the bounding rectangle must be greater than 2 units and less than 32,767 units.

### Example

[!code-cpp[NVC_MFCDocView#37](../../mfc/codesnippet/cpp/cdc-class_9.cpp)]

## <a name="playmetafile"></a> `CDC::PlayMetaFile`

Plays the contents of the specified metafile on the device context.

```
BOOL PlayMetaFile(HMETAFILE hMF);

BOOL PlayMetaFile(
    HENHMETAFILE hEnhMetaFile,
    LPCRECT lpBounds);
```

### Parameters

*`hMF`*\
Identifies the metafile to be played.

*`hEnhMetaFile`*\
Identifies the enhanced metafile.

*`lpBounds`*\
Points to a `RECT` structure or a `CRect` object that contains the coordinates of the bounding rectangle used to display the picture. The coordinates are specified in logical units.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The metafile can be played any number of times.

The second version of `PlayMetaFile` displays the picture stored in the given enhanced-format metafile. When an application calls the second version of `PlayMetaFile`, Windows uses the picture frame in the enhanced-metafile header to map the picture onto the rectangle pointed to by the *lpBounds* parameter. (This picture may be sheared or rotated by setting the world transform in the output device before calling `PlayMetaFile`.) Points along the edges of the rectangle are included in the picture. An enhanced-metafile picture can be clipped by defining the clipping region in the output device before playing the enhanced metafile.

If an enhanced metafile contains an optional palette, an application can achieve consistent colors by setting up a color palette on the output device before calling the second version of `PlayMetaFile`. To retrieve the optional palette, use the `GetEnhMetaFilePaletteEntries` Windows function. An enhanced metafile can be embedded in a newly created enhanced metafile by calling the second version of `PlayMetaFile` and playing the source enhanced metafile into the device context for the new enhanced metafile.

The states of the output device context are preserved by this function. Any object created but not deleted in the enhanced metafile is deleted by this function. To stop this function, an application can call the `CancelDC` Windows function from another thread to terminate the operation. In this case, the function returns zero.

## <a name="plgblt"></a> `CDC::PlgBlt`

Performs a bit-block transfer of the bits of color data from the specified rectangle in the source device context to the specified parallelogram in the given device context.

```
BOOL PlgBlt(
    LPPOINT lpPoint,
    CDC* pSrcDC,
    int xSrc,
    int ySrc,
    int nWidth,
    int nHeight,
    CBitmap& maskBitmap,
    int xMask,
    int yMask);
```

### Parameters

*`lpPoint`*\
Points to an array of three points in logical space that identifies three corners of the destination parallelogram. The upper-left corner of the source rectangle is mapped to the first point in this array, the upper-right corner to the second point in this array, and the lower-left corner to the third point. The lower-right corner of the source rectangle is mapped to the implicit fourth point in the parallelogram.

*`pSrcDC`*\
Identifies the source device context.

*`xSrc`*\
Specifies the x-coordinate, in logical units, of the upper-left corner of the source rectangle.

*`ySrc`*\
Specifies the y-coordinate, in logical units, of the upper-left corner of the source rectangle.

*`nWidth`*\
Specifies the width, in logical units, of the source rectangle.

*`nHeight`*\
Specifies the height, in logical units, of the source rectangle.

*`maskBitmap`*\
Identifies an optional monochrome bitmap that is used to mask the colors of the source rectangle.

*`xMask`*\
Specifies the x-coordinate of the upper-left corner of the monochrome bitmap.

*`yMask`*\
Specifies the y-coordinate of the upper-left corner of the monochrome bitmap.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

If the given bitmask handle identifies a valid monochrome bitmap, the function uses this bitmap to mask the bits of color data from the source rectangle.

The fourth vertex of the parallelogram (D) is defined by treating the first three points (A, B, and C) as vectors and computing D = B + C - A.

If the bitmask exists, a value of 1 in the mask indicates that the source pixel color should be copied to the destination. A value of 0 in the mask indicates that the destination pixel color isn't to be changed.

If the mask rectangle is smaller than the source and destination rectangles, the function replicates the mask pattern.

Scaling, translation, and reflection transformations are allowed in the source device context; however, rotation and shear transformations aren't. If the mask bitmap isn't a monochrome bitmap, an error occurs. The stretching mode for the destination device context is used to determine how to stretch or compress the pixels, if that is necessary. When an enhanced metafile is being recorded, an error occurs if the source device context identifies an enhanced-metafile device context.

The destination coordinates are transformed according to the destination device context; the source coordinates are transformed according to the source device context. If the source transformation has a rotation or shear, an error is returned. If the destination and source rectangles don't have the same color format, `PlgBlt` converts the source rectangle to match the destination rectangle. Not all devices support `PlgBlt`. For more information, see the description of the `RC_BITBLT` raster capability in the `CDC::GetDeviceCaps` member function.

If the source and destination device contexts represent incompatible devices, `PlgBlt` returns an error.

## <a name="polybezier"></a> `CDC::PolyBezier`

Draws one or more Bzier splines.

```
BOOL PolyBezier(
    const POINT* lpPoints,
    int nCount);
```

### Parameters

*`lpPoints`*\
Points to an array of [`POINT`](/windows/win32/api/windef/ns-windef-point) data structures that contain the endpoints and control points of the spline(s).

*`nCount`*\
Specifies the number of points in the *`lpPoints`* array. This value must be one more than three times the number of splines to be drawn, because each Bzier spline requires two control points and an endpoint, and the initial spline requires another starting point.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

This function draws cubic Bzier splines by using the endpoints and control points specified by the *`lpPoints`* parameter. The first spline is drawn from the first point to the fourth point by using the second and third points as control points. Each subsequent spline in the sequence needs exactly three more points: the end point of the previous spline is used as the starting point, the next two points in the sequence are control points, and the third is the end point.

The current position isn't used or updated by the `PolyBezier` function. The figure isn't filled. This function draws lines by using the current pen.

## <a name="polybezierto"></a> `CDC::PolyBezierTo`

Draws one or more Bzier splines.

```
BOOL PolyBezierTo(
    const POINT* lpPoints,
    int nCount);
```

### Parameters

*`lpPoints`*\
Points to an array of [`POINT`](/windows/win32/api/windef/ns-windef-point) data structures that contains the endpoints and control points.

*`nCount`*\
Specifies the number of points in the *`lpPoints`* array. This value must be three times the number of splines to be drawn, because each Bzier spline requires two control points and an end point.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

This function draws cubic Bzier splines by using the control points specified by the *`lpPoints`* parameter. The first spline is drawn from the current position to the third point by using the first two points as control points. For each subsequent spline, the function needs exactly three more points, and uses the end point of the previous spline as the starting point for the next. `PolyBezierTo` moves the current position to the end point of the last Bzier spline. The figure isn't filled. This function draws lines by using the current pen.

### Example

  See the example for [`CDC::BeginPath`](#beginpath).

## <a name="polydraw"></a> `CDC::PolyDraw`

Draws a set of line segments and Bzier splines.

```
BOOL PolyDraw(
    const POINT* lpPoints,
    const BYTE* lpTypes,
    int nCount);
```

### Parameters

*`lpPoints`*\
Points to an array of [`POINT`](/windows/win32/api/windef/ns-windef-point) data structures that contains the endpoints for each line segment and the endpoints and control points for each Bzier spline.

*`lpTypes`*\
Points to an array that specifies how each point in the *`lpPoints`* array is used. Values can be one of the following:

- `PT_MOVETO` Specifies that this point starts a disjoint figure. This point becomes the new current position.

- `PT_LINETO` Specifies that a line is to be drawn from the current position to this point, which then becomes the new current position.

- `PT_BEZIERTO` Specifies that this point is a control point or ending point for a Bzier spline.

`PT_BEZIERTO` types always occur in sets of three. The current position defines the starting point for the Bzier spline. The first two `PT_BEZIERTO` points are the control points, and the third `PT_BEZIERTO` point is the ending point. The ending point becomes the new current position. If there aren't three consecutive `PT_BEZIERTO` points, an error results.

   A `PT_LINETO` or `PT_BEZIERTO` type can be combined with the following constant by using the bitwise operator **OR** to indicate that the corresponding point is the last point in a figure and the figure is closed:

- `PT_CLOSEFIGURE` Specifies that the figure is automatically closed after the `PT_LINETO` or `PT_BEZIERTO` type for this point is done. A line is drawn from this point to the most recent `PT_MOVETO` or `MoveTo` point.

   This flag is combined with the `PT_LINETO` type for a line, or with the `PT_BEZIERTO` type of ending point for a Bzier spline, by using the bitwise **OR** operator. The current position is set to the ending point of the closing line.

*`nCount`*\
Specifies the total number of points in the *`lpPoints`* array, the same as the number of bytes in the *`lpTypes`* array.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

This function can be used to draw disjoint figures in place of consecutive calls to `CDC::MoveTo`, `CDC::LineTo`, and `CDC::PolyBezierTo` member functions. The lines and splines are drawn using the current pen, and figures aren't filled. If there's an active path started by calling the `CDC::BeginPath` member function, `PolyDraw` adds to the path. The points contained in the *`lpPoints`* array and in *`lpTypes`* indicate whether each point is part of a `CDC::MoveTo`, a `CDC::LineTo`, or a `CDC::BezierTo` operation. It's also possible to close figures. This function updates the current position.

### Example

  See the example for [`CDC::BeginPath`](#beginpath).

## <a name="polygon"></a> `CDC::Polygon`

Draws a polygon consisting of two or more points (vertices) connected by lines, using the current pen.

```
BOOL Polygon(
    LPPOINT lpPoints,
    int nCount);
```

### Parameters

*`lpPoints`*\
Points to an array of points that specifies the vertices of the polygon. Each point in the array is a `POINT` structure or a `CPoint` object.

*`nCount`*\
Specifies the number of vertices in the array.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The system closes the polygon automatically, if necessary, by drawing a line from the last vertex to the first.

The current polygon-filling mode can be retrieved or set by using the `GetPolyFillMode` and `SetPolyFillMode` member functions.

### Example

[!code-cpp[NVC_MFCDocView#38](../../mfc/codesnippet/cpp/cdc-class_10.cpp)]

## <a name="polyline"></a> `CDC::Polyline`

Draws a set of line segments connecting the points specified by *`lpPoints`*.

```
BOOL Polyline(
    LPPOINT lpPoints,
    int nCount);
```

### Parameters

*`lpPoints`*\
Points to an array of `POINT` structures or `CPoint` objects to be connected.

*`nCount`*\
Specifies the number of points in the array. This value must be at least 2.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The lines are drawn from the first point through subsequent points using the current pen. Unlike the `LineTo` member function, the `Polyline` function doesn't use or update the current position.

For more information, see [`PolyLine`](/windows/win32/api/wingdi/nf-wingdi-polyline) in the Windows SDK.

## <a name="polylineto"></a> `CDC::PolylineTo`

Draws one or more straight lines.

```
BOOL PolylineTo(
    const POINT* lpPoints,
    int nCount);
```

### Parameters

*`lpPoints`*\
Points to an array of [`POINT`](/windows/win32/api/windef/ns-windef-point) data structures that contains the vertices of the line.

*`nCount`*\
Specifies the number of points in the array.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

A line is drawn from the current position to the first point specified by the *`lpPoints`* parameter by using the current pen. For each additional line, the function draws from the ending point of the previous line to the next point specified by *`lpPoints`*. `PolylineTo` moves the current position to the ending point of the last line. If the line segments drawn by this function form a closed figure, the figure isn't filled.

## <a name="polypolygon"></a> `CDC::PolyPolygon`

Creates two or more polygons that are filled using the current polygon-filling mode.

```
BOOL PolyPolygon(
    LPPOINT lpPoints,
    LPINT lpPolyCounts,
    int nCount);
```

### Parameters

*`lpPoints`*\
Points to an array of `POINT` structures or `CPoint` objects that define the vertices of the polygons.

*`lpPolyCounts`*\
Points to an array of integers, each of which specifies the number of points in one of the polygons in the *`lpPoints`* array.

*`nCount`*\
The number of entries in the *`lpPolyCounts`* array. This number specifies the number of polygons to be drawn. This value must be at least 2.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The polygons may be disjoint or overlapping.

Each polygon specified in a call to the `PolyPolygon` function must be closed. Unlike polygons created by the `Polygon` member function, the polygons created by `PolyPolygon` aren't closed automatically.

The function creates two or more polygons. To create a single polygon, an application should use the `Polygon` member function.

The current polygon-filling mode can be retrieved or set by using the `GetPolyFillMode` and `SetPolyFillMode` member functions.

## <a name="polypolyline"></a> `CDC::PolyPolyline`

Draws multiple series of connected line segments.

```
BOOL PolyPolyline(
    const POINT* lpPoints,
    const DWORD* lpPolyPoints,
    int nCount);
```

### Parameters

*`lpPoints`*\
Points to an array of structures that contains the vertices of the polylines. The polylines are specified consecutively.

*`lpPolyPoints`*\
Points to an array of variables specifying the number of points in the *`lpPoints`* array for the corresponding polygon. Each entry must be greater than or equal to 2.

*`nCount`*\
Specifies the total number of counts in the *`lpPolyPoints`* array.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The line segments are drawn by using the current pen. The figures formed by the segments aren't filled. The current position isn't used or updated by this function.

## <a name="ptvisible"></a> `CDC::PtVisible`

Determines whether the given point is within the clipping region of the device context.

```
virtual BOOL PtVisible(
    int x,
    int y) const;

BOOL PtVisible(POINT point) const;
```

### Parameters

*`x`*\
Specifies the logical x-coordinate of the point.

*`y`*\
Specifies the logical y-coordinate of the point.

*`point`*\
Specifies the point to check in logical coordinates. You can pass either a `POINT` structure or a `CPoint` object for this parameter.

### Return Value

Nonzero if the specified point is within the clipping region; otherwise 0.

## <a name="queryabort"></a> `CDC::QueryAbort`

Calls the abort function installed by the [`SetAbortProc`](#setabortproc) member function for a printing application and queries whether the printing should be terminated.

```
BOOL QueryAbort() const;
```

### Return Value

The return value is nonzero if printing should continue or if there's no abort procedure. It's 0 if the print job should be terminated. The return value is supplied by the abort function.

## <a name="realizepalette"></a> `CDC::RealizePalette`

Maps entries from the current logical palette to the system palette.

```
UINT RealizePalette();
```

### Return Value

Indicates how many entries in the logical palette were mapped to different entries in the system palette. This represents the number of entries that this function remapped to accommodate changes in the system palette since the logical palette was last realized.

### Remarks

A logical color palette acts as a buffer between color-intensive applications and the system, allowing an application to use as many colors as needed without interfering with its own displayed colors or with colors displayed by other windows.

When a window has the input focus and calls `RealizePalette`, Windows ensures that the window will display all the requested colors, up to the maximum number simultaneously available on the screen. Windows also displays colors not found in the window's palette by matching them to available colors.

In addition, Windows matches the colors requested by inactive windows that call the function as closely as possible to the available colors. This significantly reduces undesirable changes in the colors displayed in inactive windows.

## <a name="rectangle"></a> `CDC::Rectangle`

Draws a rectangle using the current pen.

```
BOOL Rectangle(
    int x1,
    int y1,
    int x2,
    int y2);

BOOL Rectangle(LPCRECT lpRect);
```

### Parameters

*`x1`*\
Specifies the x-coordinate of the upper-left corner of the rectangle (in logical units).

*`y1`*\
Specifies the y-coordinate of the upper-left corner of the rectangle (in logical units).

*`x2`*\
Specifies the x-coordinate of the lower-right corner of the rectangle (in logical units).

*`y2`*\
Specifies the y-coordinate of the lower-right corner of the rectangle (in logical units).

*`lpRect`*\
Specifies the rectangle in logical units. You can pass either a `CRect` object or a pointer to a `RECT` structure for this parameter.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The interior of the rectangle is filled using the current brush.

The rectangle extends up to, but doesn't include, the right and bottom coordinates. This means that the height of the rectangle is *`y2`* - *`y1`* and the width of the rectangle is *`x2`* - *`x1`*. Both the width and the height of a rectangle must be greater than 2 units and less than 32,767 units.

### Example

[!code-cpp[NVC_MFCDocView#39](../../mfc/codesnippet/cpp/cdc-class_11.cpp)]

## <a name="rectvisible"></a> `CDC::RectVisible`

Determines whether any part of the given rectangle lies within the clipping region of the display context.

```
virtual BOOL RectVisible(LPCRECT lpRect) const;
```

### Parameters

*`lpRect`*\
Points to a `RECT` structure or a `CRect` object that contains the logical coordinates of the specified rectangle.

### Return Value

Nonzero if any portion of the given rectangle lies within the clipping region; otherwise 0.

## <a name="releaseattribdc"></a> `CDC::ReleaseAttribDC`

Call this member function to set `m_hAttribDC` to NULL.

```
virtual void ReleaseAttribDC();
```

### Remarks

This doesn't cause a `Detach` to occur. Only the output device context is attached to the `CDC` object, and only it can be detached.

## <a name="releaseoutputdc"></a> `CDC::ReleaseOutputDC`

Call this member function to set the `m_hDC` member to `NULL`.

```
virtual void ReleaseOutputDC();
```

### Remarks

This member function cannot be called when the output device context is attached to the `CDC` object. Use the `Detach` member function to detach the output device context.

## <a name="resetdc"></a> `CDC::ResetDC`

Call this member function to update the device context wrapped by the `CDC` object.

```
BOOL ResetDC(const DEVMODE* lpDevMode);
```

### Parameters

*`lpDevMode`*\
A pointer to a Windows `DEVMODE` structure.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The device context is updated from the information specified in the Windows `DEVMODE` structure. This member function only resets the attribute device context.

An application will typically use the `ResetDC` member function when a window processes a `WM_DEVMODECHANGE` message. You can also use this member function to change the paper orientation or paper bins while printing a document.

You cannot use this member function to change the driver name, device name, or output port. When the user changes the port connection or device name, you must delete the original device context and create a new device context with the new information.

Before you call this member function, you must ensure that all objects (other than stock objects) that had been selected into the device context have been selected out.

## <a name="restoredc"></a> `CDC::RestoreDC`

Restores the device context to the previous state identified by *`nSavedDC`*.

```
virtual BOOL RestoreDC(int nSavedDC);
```

### Parameters

*`nSavedDC`*\
Specifies the device context to be restored. It can be a value returned by a previous `SaveDC` function call. If *`nSavedDC`* is -1, the most recently saved device context is restored.

### Return Value

Nonzero if the specified context was restored; otherwise 0.

### Remarks

`RestoreDC` restores the device context by popping state information off a stack created by earlier calls to the `SaveDC` member function.

The stack can contain the state information for several device contexts. If the context specified by *`nSavedDC`* isn't at the top of the stack, `RestoreDC` deletes all state information between the device context specified by *`nSavedDC`* and the top of the stack. The deleted information is lost.

## <a name="roundrect"></a> `CDC::RoundRect`

Draws a rectangle with rounded corners using the current pen.

```
BOOL RoundRect(
    int x1,
    int y1,
    int x2,
    int y2,
    int x3,
    int y3);

BOOL RoundRect(
    LPCRECT lpRect,
    POINT point);
```

### Parameters

*`x1`*\
Specifies the x-coordinate of the upper-left corner of the rectangle (in logical units).

*`y1`*\
Specifies the y-coordinate of the upper-left corner of the rectangle (in logical units).

*`x2`*\
Specifies the x-coordinate of the lower-right corner of the rectangle (in logical units).

*`y2`*\
Specifies the y-coordinate of the lower-right corner of the rectangle (in logical units).

*`x3`*\
Specifies the width of the ellipse used to draw the rounded corners (in logical units).

*`y3`*\
Specifies the height of the ellipse used to draw the rounded corners (in logical units).

*`lpRect`*\
Specifies the bounding rectangle in logical units. You can pass either a `CRect` object or a pointer to a `RECT` structure for this parameter.

*`point`*\
The x-coordinate of *`point`* specifies the width of the ellipse to draw the rounded corners (in logical units). The y-coordinate of *`point`* specifies the height of the ellipse to draw the rounded corners (in logical units). You can pass either a `POINT` structure or a `CPoint` object for this parameter.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The interior of the rectangle is filled using the current brush.

The figure this function draws extends up to but doesn't include the right and bottom coordinates. This means that the height of the figure is *`y2`* - *`y1`* and the width of the figure is *`x2`* - *`x1`*. Both the height and the width of the bounding rectangle must be greater than 2 units and less than 32,767 units.

### Example

[!code-cpp[NVC_MFCDocView#40](../../mfc/codesnippet/cpp/cdc-class_12.cpp)]

## <a name="savedc"></a> `CDC::SaveDC`

Saves the current state of the device context by copying state information (such as clipping region, selected objects, and mapping mode) to a context stack maintained by Windows.

```
virtual int SaveDC();
```

### Return Value

An integer identifying the saved device context. It's 0 if an error occurs. This return value can be used to restore the device context by calling `RestoreDC`.

### Remarks

The saved device context can later be restored by using `RestoreDC`.

`SaveDC` can be used any number of times to save any number of device-context states.

## <a name="scaleviewportext"></a> `CDC::ScaleViewportExt`

Modifies the viewport extents relative to the current values.

```
virtual CSize ScaleViewportExt(
    int xNum,
    int xDenom,
    int yNum,
    int yDenom);
```

### Parameters

*`xNum`*\
Specifies the amount by which to multiply the current x-extent.

*`xDenom`*\
Specifies the amount by which to divide the result of multiplying the current x-extent by the value of the *`xNum`* parameter.

*`yNum`*\
Specifies the amount by which to multiply the current y-extent.

*`yDenom`*\
Specifies the amount by which to divide the result of multiplying the current y-extent by the value of the *`yNum`* parameter.

### Return Value

The previous viewport extents (in device units) as a `CSize` object.

### Remarks

The formulas are written as follows:

`xNewVE = ( xOldVE * xNum ) / xDenom`

`yNewVE = ( yOldVE * yNum ) / yDenom`

The new viewport extents are calculated by multiplying the current extents by the given numerator and then dividing by the given denominator.

## <a name="scalewindowext"></a> `CDC::ScaleWindowExt`

Modifies the window extents relative to the current values.

```
virtual CSize ScaleWindowExt(
    int xNum,
    int xDenom,
    int yNum,
    int yDenom);
```

### Parameters

*`xNum`*\
Specifies the amount by which to multiply the current x-extent.

*`xDenom`*\
Specifies the amount by which to divide the result of multiplying the current x-extent by the value of the *`xNum`* parameter.

*`yNum`*\
Specifies the amount by which to multiply the current y-extent.

*`yDenom`*\
Specifies the amount by which to divide the result of multiplying the current y-extent by the value of the *`yNum`* parameter.

### Return Value

The previous window extents (in logical units) as a `CSize` object.

### Remarks

The formulas are written as follows:

`xNewWE = ( xOldWE * xNum ) / xDenom`

`yNewWE = ( yOldWE * yNum ) / yDenom`

The new window extents are calculated by multiplying the current extents by the given numerator and then dividing by the given denominator.

## <a name="scrolldc"></a> `CDC::ScrollDC`

Scrolls a rectangle of bits horizontally and vertically.

```
BOOL ScrollDC(
    int dx,
    int dy,
    LPCRECT lpRectScroll,
    LPCRECT lpRectClip,
    CRgn* pRgnUpdate,
    LPRECT lpRectUpdate);
```

### Parameters

*`dx`*\
Specifies the number of horizontal scroll units.

*`dy`*\
Specifies the number of vertical scroll units.

*`lpRectScroll`*\
Points to the `RECT` structure or `CRect` object that contains the coordinates of the scrolling rectangle.

*`lpRectClip`*\
Points to the `RECT` structure or `CRect` object that contains the coordinates of the clipping rectangle. When this rectangle is smaller than the original one pointed to by *`lpRectScroll`*, scrolling occurs only in the smaller rectangle.

*`pRgnUpdate`*\
Identifies the region uncovered by the scrolling process. The `ScrollDC` function defines this region; it isn't necessarily a rectangle.

*`lpRectUpdate`*\
Points to the `RECT` structure or `CRect` object that receives the coordinates of the rectangle that bounds the scrolling update region. This is the largest rectangular area that requires repainting. The values in the structure or object when the function returns are in client coordinates, regardless of the mapping mode for the given device context.

### Return Value

Nonzero if scrolling is executed; otherwise 0.

### Remarks

If *`lpRectUpdate`* is `NULL`, Windows doesn't compute the update rectangle. If both *`pRgnUpdate`* and *`lpRectUpdate`* are `NULL`, Windows doesn't compute the update region. If *`pRgnUpdate`* isn't `NULL`, Windows assumes that it contains a valid pointer to the region uncovered by the scrolling process (defined by the `ScrollDC` member function). The update region returned in *`lpRectUpdate`* can be passed to `CWnd::InvalidateRgn` if required.

An application should use the `ScrollWindow` member function of class `CWnd` when it's necessary to scroll the entire client area of a window. Otherwise, it should use `ScrollDC`.

## <a name="selectclippath"></a> `CDC::SelectClipPath`

Selects the current path as a clipping region for the device context, combining the new region with any existing clipping region by using the specified mode.

```
BOOL SelectClipPath(int nMode);
```

### Parameters

*`nMode`*\
Specifies the way to use the path. The following values are allowed:

- `RGN_AND` The new clipping region includes the intersection (overlapping areas) of the current clipping region and the current path.

- `RGN_COPY` The new clipping region is the current path.

- `RGN_DIFF` The new clipping region includes the areas of the current clipping region, and those of the current path are excluded.

- `RGN_OR` The new clipping region includes the union (combined areas) of the current clipping region and the current path.

- `RGN_XOR` The new clipping region includes the union of the current clipping region and the current path, but without the overlapping areas.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The device context identified must contain a closed path.

## <a name="selectcliprgn"></a> `CDC::SelectClipRgn`

Selects the given region as the current clipping region for the device context.

```
int SelectClipRgn(CRgn* pRgn);

int SelectClipRgn(
    CRgn* pRgn,
    int nMode);
```

### Parameters

*`pRgn`*\
Identifies the region to be selected.

- For the first version of this function, if this value is `NULL`, the entire client area is selected and output is still clipped to the window.

- For the second version of this function, this handle can be `NULL` only when the `RGN_COPY` mode is specified.

*`nMode`*\
Specifies the operation to be performed. It must be one of the following values:

- `RGN_AND` The new clipping region combines the overlapping areas of the current clipping region and the region identified by *`pRgn`*.

- `RGN_COPY` The new clipping region is a copy of the region identified by *`pRgn`*. This is functionality is identical to the first version of `SelectClipRgn`. If the region identified by *`pRgn`* is `NULL`, the new clipping region becomes the default clipping region (a null region).

- `RGN_DIFF` The new clipping region combines the areas of the current clipping region with those areas excluded from the region identified by *`pRgn`*.

- `RGN_OR` The new clipping region combines the current clipping region and the region identified by *`pRgn`*.

- `RGN_XOR` The new clipping region combines the current clipping region and the region identified by *`pRgn`* but excludes any overlapping areas.

### Return Value

The region's type. It can be any of the following values:

- `COMPLEXREGION` New clipping region has overlapping borders.

- `ERROR` Device context or region isn't valid.

- `NULLREGION` New clipping region is empty.

- `SIMPLEREGION` New clipping region has no overlapping borders.

### Remarks

Only a copy of the selected region is used. The region itself can be selected for any number of other device contexts, or it can be deleted.

The function assumes that the coordinates for the given region are specified in device units. Some printer devices support text output at a higher resolution than graphics output in order to retain the precision needed to express text metrics. These devices report device units at the higher resolution, that is, in text units. These devices then scale coordinates for graphics so that several reported device units map to only 1 graphic unit. You should always call the `SelectClipRgn` function using text units.

Applications that must take the scaling of graphics objects in the GDI can use the `GETSCALINGFACTOR` printer escape to determine the scaling factor. This scaling factor affects clipping. If a region is used to clip graphics, GDI divides the coordinates by the scaling factor. If the region is used to clip text, GDI makes no scaling adjustment. A scaling factor of 1 causes the coordinates to be divided by 2; a scaling factor of 2 causes the coordinates to be divided by 4; and so on.

## <a name="selectobject"></a> `CDC::SelectObject`

Selects an object into the device context.

```
CPen* SelectObject(CPen* pPen);
CBrush* SelectObject(CBrush* pBrush);
virtual CFont* SelectObject(CFont* pFont);
CBitmap* SelectObject(CBitmap* pBitmap);
int SelectObject(CRgn* pRgn);
CGdiObject* SelectObject(CGdiObject* pObject);
```

### Parameters

*`pPen`*\
A pointer to a [`CPen`](../../mfc/reference/cpen-class.md) object to be selected.

*`pBrush`*\
A pointer to a [`CBrush`](../../mfc/reference/cbrush-class.md) object to be selected.

*`pFont`*\
A pointer to a [`CFont`](../../mfc/reference/cfont-class.md) object to be selected.

*`pBitmap`*\
A pointer to a [`CBitmap`](../../mfc/reference/cbitmap-class.md) object to be selected.

*`pRgn`*\
A pointer to a [`CRgn`](../../mfc/reference/crgn-class.md) object to be selected.

*`pObject`*\
A pointer to a [`CGdiObject`](../../mfc/reference/cgdiobject-class.md) object to be selected.

### Return Value

A pointer to the object being replaced. This is a pointer to an object of one of the classes derived from `CGdiObject`, such as `CPen`, depending on which version of the function is used. The return value is `NULL` if there's an error. This function may return a pointer to a temporary object. This temporary object is only valid during the processing of one Windows message. For more information, see `CGdiObject::FromHandle`.

The version of the member function that takes a region parameter performs the same task as the `SelectClipRgn` member function. Its return value can be any of the following:

- `COMPLEXREGION` New clipping region has overlapping borders.

- `ERROR` Device context or region isn't valid.

- `NULLREGION` New clipping region is empty.

- `SIMPLEREGION` New clipping region has no overlapping borders.

### Remarks

Class `CDC` provides five versions specialized for particular kinds of GDI objects, including pens, brushes, fonts, bitmaps, and regions. The newly selected object replaces the previous object of the same type. For example, if *`pObject`* of the general version of `SelectObject` points to a [`CPen`](../../mfc/reference/cpen-class.md) object, the function replaces the current pen with the pen specified by *`pObject`*.

An application can select a bitmap into memory device contexts only and into only one memory device context at a time. The format of the bitmap must either be monochrome or compatible with the device context; if it isn't, `SelectObject` returns an error.

For Windows 3.1 and later, the `SelectObject` function returns the same value whether it's used in a metafile or not. Under previous versions of Windows, `SelectObject` returned a nonzero value for success and 0 for failure when it was used in a metafile.

## <a name="selectpalette"></a> `CDC::SelectPalette`

Selects the logical palette that is specified by *`pPalette`* as the selected palette object of the device context.

```
CPalette* SelectPalette(
    CPalette* pPalette,
    BOOL bForceBackground);
```

### Parameters

*`pPalette`*\
Identifies the logical palette to be selected. This palette must already have been created with the `CPalette` member function [`CreatePalette`](../../mfc/reference/cpalette-class.md#createpalette).

*`bForceBackground`*\
Specifies whether the logical palette is forced to be a background palette. If *`bForceBackground`* is nonzero, the selected palette is always a background palette, regardless of whether the window has the input focus. If *`bForceBackground`* is 0 and the device context is attached to a window, the logical palette is a foreground palette when the window has the input focus.

### Return Value

A pointer to a `CPalette` object identifying the logical palette replaced by the palette specified by *`pPalette`*. It's `NULL` if there's an error.

### Remarks

The new palette becomes the palette object used by GDI to control colors displayed in the device context and replaces the previous palette.

An application can select a logical palette into more than one device context. However, changes to a logical palette will affect all device contexts for which it's selected. If an application selects a palette into more than one device context, the device contexts must all belong to the same physical device.

## <a name="selectstockobject"></a> `CDC::SelectStockObject`

Selects a [`CGdiObject`](../../mfc/reference/cgdiobject-class.md) object that corresponds to one of the predefined stock pens, brushes, or fonts.

```
virtual CGdiObject* SelectStockObject(int nIndex);
```

### Parameters

*`nIndex`*\
Specifies the kind of stock object desired. It can be one of the following values:

- `BLACK_BRUSH` Black brush.

- `DKGRAY_BRUSH` Dark gray brush.

- `GRAY_BRUSH` Gray brush.

- `HOLLOW_BRUSH` Hollow brush.

- `LTGRAY_BRUSH` Light gray brush.

- `NULL_BRUSH` Null brush.

- `WHITE_BRUSH` White brush.

- `BLACK_PEN` Black pen.

- `NULL_PEN` Null pen.

- `WHITE_PEN` White pen.

- `ANSI_FIXED_FONT` ANSI fixed system font.

- `ANSI_VAR_FONT` ANSI variable system font.

- `DEVICE_DEFAULT_FONT` Device-dependent font.

- `OEM_FIXED_FONT` OEM-dependent fixed font.

- `SYSTEM_FONT` The system font. By default, Windows uses the system font to draw menus, dialog-box controls, and other text. It's best, however, not to rely on `SYSTEM_FONT` to obtain the font used by dialogs and windows. Instead, use the `SystemParametersInfo` function with the `SPI_GETNONCLIENTMETRICS` parameter to retrieve the current font. `SystemParametersInfo` takes into account the current theme and provides font information for captions, menus, and message dialogs.

- `SYSTEM_FIXED_FONT` The fixed-width system font used in Windows prior to version 3.0. This object is available for compatibility with earlier versions of Windows.

- `DEFAULT_PALETTE` Default color palette. This palette consists of the 20 static colors in the system palette.

### Return Value

A pointer to the `CGdiObject` object that was replaced if the function is successful. The actual object pointed to is a [`CPen`](../../mfc/reference/cpen-class.md), [`CBrush`](../../mfc/reference/cbrush-class.md), or [`CFont`](../../mfc/reference/cfont-class.md) object. If the call is unsuccessful, the return value is NULL.

## <a name="setabortproc"></a> `CDC::SetAbortProc`

Installs the abort procedure for the print job.

```
int SetAbortProc(BOOL (CALLBACK* lpfn)(HDC, int));
```

### Parameters

*`lpfn`*\
A pointer to the abort function to install as the abort procedure. For more about the callback function, see [Callback Function for `CDC::SetAbortProc`](callback-functions-used-by-mfc.md#setabortproc).

### Return Value

Specifies the outcome of the `SetAbortProc` function. Some of the following values are more probable than others, but all are possible.

- `SP_ERROR` General error.

- `SP_OUTOFDISK` Not enough disk space is currently available for spooling, and no more space will become available.

- `SP_OUTOFMEMORY` Not enough memory is available for spooling.

- `SP_USERABORT` User ended the job through the Print Manager.

### Remarks

If an application is to allow the print job to be canceled during spooling, it must set the abort function before the print job is started with the [`StartDoc`](#startdoc) member function. The Print Manager calls the abort function during spooling to allow the application to cancel the print job or to process out-of-disk-space conditions. If no abort function is set, the print job will fail if there isn't enough disk space for spooling.

The features of Visual Studio simplify the creation of the callback function passed to `SetAbortProc`. The address passed to the `EnumObjects` member function is a pointer to a function exported with `__declspec(dllexport)` and with the **`__stdcall`** calling convention.

You also don't have to export the function name in an **`EXPORTS`** statement in your application's module-definition file. You can instead use the **`EXPORT`** function modifier, as in

`BOOL CALLBACK EXPORT AFunction( HDC, int );`

to cause the compiler to emit the proper export record for export by name without aliasing. This works for most needs. For some special cases, such as exporting a function by ordinal or aliasing the export, you still need to use an **`EXPORTS`** statement in a module-definition file.

Callback registration interfaces are now type-safe (you must pass in a function pointer that points to the right kind of function for the specific callback).

All callback functions must trap Microsoft Foundation exceptions before returning to Windows, since exceptions cannot be thrown across callback boundaries. For more information about exceptions, see the article [Exceptions](../../mfc/exception-handling-in-mfc.md).

## <a name="setarcdirection"></a> `CDC::SetArcDirection`

Sets the drawing direction to be used for arc and rectangle functions.

```
int SetArcDirection(int nArcDirection);
```

### Parameters

*`nArcDirection`*\
Specifies the new arc direction. This parameter can be either of the following values:

- `AD_COUNTERCLOCKWISE` Figures drawn counterclockwise.

- `AD_CLOCKWISE` Figures drawn clockwise.

### Return Value

Specifies the old arc direction, if successful; otherwise 0.

### Remarks

The default direction is counterclockwise. The `SetArcDirection` function specifies the direction in which the following functions draw:

|Arc|Pie|
|---------|---------|
|`ArcTo`|`Rectangle`|
|`Chord`|`RoundRect`|
|`Ellipse`||

## <a name="setattribdc"></a> `CDC::SetAttribDC`

Call this function to set the attribute device context, `m_hAttribDC`.

```
virtual void SetAttribDC(HDC hDC);
```

### Parameters

*`hDC`*\
A Windows device context.

### Remarks

This member function doesn't attach the device context to the `CDC` object. Only the output device context is attached to a `CDC` object.

## <a name="setbkcolor"></a> `CDC::SetBkColor`

Sets the current background color to the specified color.

```
virtual COLORREF SetBkColor(COLORREF crColor);
```

### Parameters

*`crColor`*\
Specifies the new background color.

### Return Value

The previous background color as an RGB color value. If an error occurs, the return value is 0x80000000.

### Remarks

If the background mode is `OPAQUE`, the system uses the background color to fill the gaps in styled lines, the gaps between hatched lines in brushes, and the background in character cells. The system also uses the background color when converting bitmaps between color and monochrome device contexts.

If the device cannot display the specified color, the system sets the background color to the nearest physical color.

## <a name="setbkmode"></a> `CDC::SetBkMode`

Sets the background mode.

```
int SetBkMode(int nBkMode);
```

### Parameters

*`nBkMode`*\
Specifies the mode to be set. This parameter can be either of the following values:

- `OPAQUE` Background is filled with the current background color before the text, hatched brush, or pen is drawn. This is the default background mode.

- `TRANSPARENT` Background isn't changed before drawing.

### Return Value

The previous background mode.

### Remarks

The background mode defines whether the system removes existing background colors on the drawing surface before drawing text, hatched brushes, or any pen style that isn't a solid line.

### Example

  See the example for [`CWnd::OnCtlColor`](../../mfc/reference/cwnd-class.md#onctlcolor).

## <a name="setboundsrect"></a> `CDC::SetBoundsRect`

Controls the accumulation of bounding-rectangle information for the specified device context.

```
UINT SetBoundsRect(
    LPCRECT lpRectBounds,
    UINT flags);
```

### Parameters

*`lpRectBounds`*\
Points to a `RECT` structure or `CRect` object that is used to set the bounding rectangle. Rectangle dimensions are given in logical coordinates. This parameter can be `NULL`.

*`flags`*\
Specifies how the new rectangle will be combined with the accumulated rectangle. This parameter can be a combination of the following values:

- `DCB_ACCUMULATE` Add the rectangle specified by *`lpRectBounds`* to the bounding rectangle (using a rectangle-union operation).

- `DCB_DISABLE` Turn off bounds accumulation.

- `DCB_ENABLE` Turn on bounds accumulation. (The default setting for bounds accumulation is disabled.)

### Return Value

The current state of the bounding rectangle, if the function is successful. Like *`flags`*, the return value can be a combination of **`DCB_`** values:

- `DCB_ACCUMULATE` The bounding rectangle isn't empty. This value will always be set.

- `DCB_DISABLE` Bounds accumulation is off.

- `DCB_ENABLE` Bounds accumulation is on.

### Remarks

Windows can maintain a bounding rectangle for all drawing operations. This rectangle can be queried and reset by the application. The drawing bounds are useful for invalidating bitmap caches.

## <a name="setbrushorg"></a> `CDC::SetBrushOrg`

Specifies the origin that GDI will assign to the next brush that the application selects into the device context.

```
CPoint SetBrushOrg(
    int x,
    int y);

CPoint SetBrushOrg(POINT point);
```

### Parameters

*`x`*\
Specifies the x-coordinate (in device units) of the new origin. This value must be in the range 0-7.

*`y`*\
Specifies the y-coordinate (in device units) of the new origin. This value must be in the range 0-7.

*`point`*\
Specifies the x- and y-coordinates of the new origin. Each value must be in the range 0-7. You can pass either a `POINT` structure or a `CPoint` object for this parameter.

### Return Value

The previous origin of the brush in device units.

### Remarks

The default coordinates for the brush origin are (0, 0). To alter the origin of a brush, call the `UnrealizeObject` function for the `CBrush` object, call `SetBrushOrg`, and then call the `SelectObject` member function to select the brush into the device context.

Don't use `SetBrushOrg` with stock `CBrush` objects.

## <a name="setcoloradjustment"></a> `CDC::SetColorAdjustment`

Sets the color adjustment values for the device context using the specified values.

```
BOOL SetColorAdjustment(const COLORADJUSTMENT* lpColorAdjust);
```

### Parameters

*`lpColorAdjust`*\
Points to a [`COLORADJUSTMENT`](/windows/win32/api/wingdi/ns-wingdi-coloradjustment) data structure containing the color adjustment values.

### Return Value

Nonzero if successful; otherwise 0.

### Remarks

The color adjustment values are used to adjust the input color of the source bitmap for calls to the `CDC::StretchBlt` member function when `HALFTONE` mode is set.

## <a name="setdcbrushcolor"></a> `CDC::SetDCBrushColor`

Sets the current device context (DC) brush color to the specified color value.

```
COLORREF SetDCBrushColor(COLORREF crColor);
```

### Parameters

*`crColor`*\
Specifies the new brush color.

### Return Value

If the function succeeds, the return value specifies the previous DC brush color as a `COLORREF` value.

If the function fails, the return value is `CLR_INVALID`.

### Remarks

This method emulates the functionality of the function [`SetDCBrushColor`](/windows/win32/api/wingdi/nf-wingdi-setdcbrushcolor), as described in the Windows SDK.

## <a name="setdcpencolor"></a> `CDC::SetDCPenColor`

Sets the current device context (DC) pen color to the specified color value.

```
COLORREF SetDCPenColor(COLORREF crColor);
```

### Parameters

*`crColor`*\
Specifies the new pen color.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

This member function utilizes the Win32 function [`SetDCPenColor`](/windows/win32/api/wingdi/nf-wingdi-setdcpencolor), as described in the Windows SDK.

## <a name="setgraphicsmode"></a> `CDC::SetGraphicsMode`

Sets the graphics mode for the specified device context.

```
int SetGraphicsMode(int iMode);
```

### Parameters

*`iMode`*\
Specifies the graphics mode. For a list of the values that this parameter can take, see [`SetGraphicsMode`](/windows/win32/api/wingdi/nf-wingdi-setgraphicsmode).

### Return Value

Returns the old graphics mode on success.

Returns 0 on failure. To get extended error information, call [`GetLastError`](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror).

### Remarks

This method wraps the Windows GDI function [`SetGraphicsMode`](/windows/win32/api/wingdi/nf-wingdi-setgraphicsmode).

## <a name="setlayout"></a> `CDC::SetLayout`

Call this member function to change the layout of the text and graphics for a device context to right to left, the standard layout for cultures such as Arabic and Hebrew.

```
DWORD SetLayout(DWORD dwLayout);
```

### Parameters

*`dwLayout`*\
Device context layout and bitmap control flags. It can be a combination of the following values.

|Value|Meaning|
|-----------|-------------|
|`LAYOUT_BITMAPORIENTATIONPRESERVED`|Disables any reflection for calls to [`CDC::BitBlt`](#bitblt) and [`CDC::StretchBlt`](#stretchblt).|
|`LAYOUT_RTL`|Sets the default horizontal layout to be right to left.|
|`LAYOUT_LTR`|Sets the default layout to be left to right.|

### Return Value

If successful, the previous layout of the device context.

If unsuccessful, `GDI_ERROR`. To get extended error information, call [`GetLastError`](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror).

### Remarks

Normally, you would not call `SetLayout` for a window. Rather, you control the right-to-left layout in a window by setting the [extended window styles](../../mfc/reference/styles-used-by-mfc.md#extended-window-styles) such as `WS_EX_RTLREADING`. A device context, such as a printer or a metafile, doesn't inherit this layout. The only way to set the device context for a right-to-left layout is by calling `SetLayout`.

If you call **`SetLayout(LAYOUT_RTL)`**, `SetLayout` automatically changes the mapping mode to `MM_ISOTROPIC`. As a result, a subsequent call to [`GetMapMode`](#getmapmode) will return `MM_ISOTROPIC` instead of `MM_TEXT`.

In some cases, such as with many bitmaps, you may want to preserve the left-to-right layout. In these cases, render the image by calling `BitBlt` or `StretchBlt`, then set the bitmap control flag for *`dwLayout`* to `LAYOUT_BITMAPORIENTATIONPRESERVED`.

Once you change the layout with the `LAYOUT_RTL` flag, the flags normally specifying right or left are reversed. To avoid confusion, you may want to define alternate names for the standard flags. For a list of suggested alternate flag names, see [`SetLayout`](/windows/win32/api/wingdi/nf-wingdi-setlayout) in the Windows SDK.

## <a name="setmapmode"></a> `CDC::SetMapMode`

Sets the mapping mode.

```
virtual int SetMapMode(int nMapMode);
```

### Parameters

*`nMapMode`*\
Specifies the new mapping mode. It can be any one of the following values:

- `MM_ANISOTROPIC` Logical units are converted to arbitrary units with arbitrarily scaled axes. Setting the mapping mode to `MM_ANISOTROPIC` doesn't change the current window or viewport settings. To change the units, orientation, and scaling, call the [`SetWindowExt`](#setwindowext) and [`SetViewportExt`](#setviewportext) member functions.

- `MM_HIENGLISH` Each logical unit is converted to 0.001 inch. Positive x is to the right; positive y is up.

- `MM_HIMETRIC` Each logical unit is converted to 0.01 millimeter. Positive x is to the right; positive y is up.

- `MM_ISOTROPIC` Logical units are converted to arbitrary units with equally scaled axes; that is, 1 unit along the x-axis is equal to 1 unit along the y-axis. Use the `SetWindowExt` and `SetViewportExt` member functions to specify the desired units and the orientation of the axes. GDI makes adjustments as necessary to ensure that the x and y units remain the same size.

- `MM_LOENGLISH` Each logical unit is converted to 0.01 inch. Positive x is to the right; positive y is up.

- `MM_LOMETRIC` Each logical unit is converted to 0.1 millimeter. Positive x is to the right; positive y is up.

- `MM_TEXT` Each logical unit is converted to 1 device pixel. Positive x is to the right; positive y is down.

- `MM_TWIPS` Each logical unit is converted to 1/20 of a point. (Because a point is 1/72 inch, a twip is 1/1440 inch.) Positive x is to the right; positive y is up.

### Return Value

The previous mapping mode.

### Remarks

The mapping mode defines the unit of measure used to convert logical units to device units; it also defines the orientation of the device's x- and y-axes. GDI uses the mapping mode to convert logical coordinates into the appropriate device coordinates. The `MM_TEXT` mode allows applications to work in device pixels, where 1 unit is equal to 1 pixel. The physical size of a pixel varies from device to device.

The `MM_HIENGLISH`, `MM_HIMETRIC`, `MM_LOENGLISH`, `MM_LOMETRIC`, and `MM_TWIPS` modes are useful for applications that must draw in physically meaningful units (such as inches or millimeters). The `MM_ISOTROPIC` mode ensures a 1:1 aspect ratio, which is useful when it's important to preserve the exact shape of an image. The `MM_ANISOTROPIC` mode allows the x- and y-coordinates to be adjusted independently.

> [!NOTE]
> If you call [`SetLayout`](#setlayout) to change the DC (device context) to right-to-left layout, `SetLayout` automatically changes the mapping mode to `MM_ISOTROPIC`.

### Example

  See the example for [`CView::OnPrepareDC`](../../mfc/reference/cview-class.md#onpreparedc).

## <a name="setmapperflags"></a> `CDC::SetMapperFlags`

Changes the method used by the font mapper when it converts a logical font to a physical font.

```
DWORD SetMapperFlags(DWORD dwFlag);
```

### Parameters

*`dwFlag`*\
Specifies whether the font mapper attempts to match a font's aspect height and width to the device. When this value is `ASPECT_FILTERING`, the mapper selects only fonts whose x-aspect and y-aspect exactly match those of the specified device.

### Return Value

The previous value of the font-mapper flag.

### Remarks

An application can use `SetMapperFlags` to cause the font mapper to attempt to choose only a physical font that exactly matches the aspect ratio of the specified device.

An application that uses only raster fonts can use the `SetMapperFlags` function to ensure that the font selected by the font mapper is attractive and readable on the specified device. Applications that use scalable (TrueType) fonts typically don't use `SetMapperFlags`.

If no physical font has an aspect ratio that matches the specification in the logical font, GDI chooses a new aspect ratio and selects a font that matches this new aspect ratio.

## <a name="setmiterlimit"></a> `CDC::SetMiterLimit`

Sets the limit for the length of miter joins for the device context.

```
BOOL SetMiterLimit(float fMiterLimit);
```

### Parameters

*`fMiterLimit`*\
Specifies the new miter limit for the device context.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The miter length is defined as the distance from the intersection of the line walls on the inside of the join to the intersection of the line walls on the outside of the join. The miter limit is the maximum allowed ratio of the miter length to the line width. The default miter limit is 10.0.

## <a name="setoutputdc"></a> `CDC::SetOutputDC`

Call this member function to set the output device context, `m_hDC`.

```
virtual void SetOutputDC(HDC hDC);
```

### Parameters

*`hDC`*\
A Windows device context.

### Remarks

This member function can only be called when a device context has not been attached to the `CDC` object. This member function sets `m_hDC` but doesn't attach the device context to the `CDC` object.

## <a name="setpixel"></a> `CDC::SetPixel`

Sets the pixel at the point specified to the closest approximation of the color specified by *`crColor`*.

```
COLORREF SetPixel(
    int x,
    int y,
    COLORREF crColor);

COLORREF SetPixel(
    POINT point,
    COLORREF crColor);
```

### Parameters

*`x`*\
Specifies the logical x-coordinate of the point to be set.

*`y`*\
Specifies the logical y-coordinate of the point to be set.

*`crColor`*\
A `COLORREF` RGB value that specifies the color used to paint the point. See [`COLORREF`](/windows/win32/gdi/colorref) in the Windows SDK for a description of this value.

*`point`*\
Specifies the logical x- and y-coordinates of the point to be set. You can pass either a `POINT` structure or a `CPoint` object for this parameter.

### Return Value

An RGB value for the color that the point is painted. This value can be different from that specified by *`crColor`* if an approximation of that color is used. If the function fails (if the point is outside the clipping region), the return value is -1.

### Remarks

The point must be in the clipping region. If the point isn't in the clipping region, the function does nothing.

Not all devices support the `SetPixel` function. To determine whether a device supports `SetPixel`, call the `GetDeviceCaps` member function with the `RASTERCAPS` index and check the return value for the `RC_BITBLT` flag.

## <a name="setpixelv"></a> `CDC::SetPixelV`

Sets the pixel at the specified coordinates to the closest approximation of the specified color.

```
BOOL SetPixelV(
    int x,
    int y,
    COLORREF crColor);

BOOL SetPixelV(
    POINT point,
    COLORREF crColor);
```

### Parameters

*`x`*\
Specifies the x-coordinate, in logical units, of the point to be set.

*`y`*\
Specifies the y-coordinate, in logical units, of the point to be set.

*`crColor`*\
Specifies the color to be used to paint the point.

*`point`*\
Specifies the logical x- and y-coordinates of the point to be set. You can pass either a [`POINT`](/windows/win32/api/windef/ns-windef-point) data structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object for this parameter.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The point must be in both the clipping region and the visible part of the device surface. Not all devices support the member function. For more information, see the `RC_BITBLT` capability in the `CDC::GetDeviceCaps` member function. `SetPixelV` is faster than `SetPixel` because it doesn't need to return the color value of the point painted.

## <a name="setpolyfillmode"></a> `CDC::SetPolyFillMode`

Sets the polygon-filling mode.

```
int SetPolyFillMode(int nPolyFillMode);
```

### Parameters

*`nPolyFillMode`*\
Specifies the new filling mode. This value may be either `ALTERNATE` or `WINDING`. The default mode set in Windows is `ALTERNATE`.

### Return Value

The previous filling mode, if successful; otherwise 0.

### Remarks

When the polygon-filling mode is `ALTERNATE`, the system fills the area between odd-numbered and even-numbered polygon sides on each scan line. That is, the system fills the area between the first and second side, between the third and fourth side, and so on. This mode is the default.

When the polygon-filling mode is `WINDING`, the system uses the direction in which a figure was drawn to determine whether to fill an area. Each line segment in a polygon is drawn in either a clockwise or a counterclockwise direction. Whenever an imaginary line drawn from an enclosed area to the outside of a figure passes through a clockwise line segment, a count is incremented. When the line passes through a counterclockwise line segment, the count is decremented. The area is filled if the count is nonzero when the line reaches the outside of the figure.

## <a name="setrop2"></a> `CDC::SetROP2`

Sets the current drawing mode.

```
int SetROP2(int nDrawMode);
```

### Parameters

*`nDrawMode`*\
Specifies the new drawing mode. It can be any of the following values:

- `R2_BLACK` Pixel is always black.

- `R2_WHITE` Pixel is always white.

- `R2_NOP` Pixel remains unchanged.

- `R2_NOT` Pixel is the inverse of the screen color.

- `R2_COPYPEN` Pixel is the pen color.

- `R2_NOTCOPYPEN` Pixel is the inverse of the pen color.

- `R2_MERGEPENNOT` Pixel is a combination of the pen color and the inverse of the screen color (final pixel = (`~` screen pixel) `|` pen).

- `R2_MASKPENNOT` Pixel is a combination of the colors common to both the pen and the inverse of the screen (final pixel = (`~` screen pixel) `&` pen).

- `R2_MERGENOTPEN` Pixel is a combination of the screen color and the inverse of the pen color (final pixel = (`~` pen) `|` screen pixel).

- `R2_MASKNOTPEN` Pixel is a combination of the colors common to both the screen and the inverse of the pen (final pixel = (`~` pen) `&` screen pixel).

- `R2_MERGEPEN` Pixel is a combination of the pen color and the screen color (final pixel = pen `|` screen pixel).

- `R2_NOTMERGEPEN` Pixel is the inverse of the `R2_MERGEPEN` color (final pixel = `~` (pen `|` screen pixel)).

- `R2_MASKPEN` Pixel is a combination of the colors common to both the pen and the screen (final pixel = pen `&` screen pixel).

- `R2_NOTMASKPEN` Pixel is the inverse of the `R2_MASKPEN` color (final pixel = `~` (pen `&` screen pixel)).

- `R2_XORPEN` Pixel is a combination of the colors that are in the pen or in the screen, but not in both (final pixel = pen `^` screen pixel).

- `R2_NOTXORPEN` Pixel is the inverse of the `R2_XORPEN` color (final pixel = `~` (pen `^` screen pixel)).

### Return Value

The previous drawing mode.

It can be any of the values given in the Windows SDK.

### Remarks

The drawing mode specifies how the colors of the pen and the interior of filled objects are combined with the color already on the display surface.

The drawing mode is for raster devices only; it doesn't apply to vector devices. Drawing modes are binary raster-operation codes representing all possible Boolean combinations of two variables, using the binary operators `&`, `|`, and `^` (exclusive `|`), and the unary operation `~`.

## <a name="setstretchbltmode"></a> `CDC::SetStretchBltMode`

Sets the bitmap-stretching mode for the `StretchBlt` member function.

```
int SetStretchBltMode(int nStretchMode);
```

### Parameters

*`nStretchMode`*\
Specifies the stretching mode. It can be any of the following values:

|Value|Description|
|-----------|-----------------|
|`BLACKONWHITE`|Performs a Boolean `&` operation using the color values for the eliminated and existing pixels. If the bitmap is a monochrome bitmap, this mode preserves black pixels at the expense of white pixels.|
|`COLORONCOLOR`|Deletes the pixels. This mode deletes all eliminated lines of pixels without trying to preserve their information.|
|`HALFTONE`|Maps pixels from the source rectangle into blocks of pixels in the destination rectangle. The average color over the destination block of pixels approximates the color of the source pixels.|
||After setting the `HALFTONE` stretching mode, an application must call the Win32 function [`SetBrushOrgEx`](/windows/win32/api/wingdi/nf-wingdi-setbrushorgex) to set the brush origin. If it fails to do so, brush misalignment occurs.|
|`STRETCH_ANDSCANS`|**Windows 95/98**: Same as `BLACKONWHITE`|
|`STRETCH_DELETESCANS`|**Windows 95/98**: Same as `COLORONCOLOR`|
|`STRETCH_HALFTONE`|**Windows 95/98**: Same as `HALFTONE`.|
|`STRETCH_ORSCANS`|**Windows 95/98**: Same as `WHITEONBLACK`|
|`WHITEONBLACK`|Performs a Boolean `|` operation using the color values for the eliminated and existing pixels. If the bitmap is a monochrome bitmap, this mode preserves white pixels at the expense of black pixels.|

### Return Value

The previous stretching mode. It can be `STRETCH_ANDSCANS`, `STRETCH_DELETESCANS`, or `STRETCH_ORSCANS`.

### Remarks

The bitmap-stretching mode defines how information is removed from bitmaps that are compressed by using the function.

The `BLACKONWHITE`(`STRETCH_ANDSCANS`) and `WHITEONBLACK`(`STRETCH_ORSCANS`) modes are typically used to preserve foreground pixels in monochrome bitmaps. The `COLORONCOLOR`(`STRETCH_DELETESCANS`) mode is typically used to preserve color in color bitmaps.

The `HALFTONE` mode requires more processing of the source image than the other three modes; it's slower than the others, but produces higher quality images. Also, `SetBrushOrgEx` must be called after setting the `HALFTONE` mode to avoid brush misalignment.

More stretching modes might also be available depending on the capabilities of the device driver.

## <a name="settextalign"></a> `CDC::SetTextAlign`

Sets the text-alignment flags.

```
UINT SetTextAlign(UINT nFlags);
```

### Parameters

*`nFlags`*\
Specifies text-alignment flags. The flags specify the relationship between a point and a rectangle that bounds the text. The point can be either the current position or coordinates specified by a text-output function. The rectangle that bounds the text is defined by the adjacent character cells in the text string. The *`nFlags`* parameter can be one or more flags from the following three categories. Choose only one flag from each category. The first category affects text alignment in the x-direction:

- `TA_CENTER` Aligns the point with the horizontal center of the bounding rectangle.

- `TA_LEFT` Aligns the point with the left side of the bounding rectangle. This is the default setting.

- `TA_RIGHT` Aligns the point with the right side of the bounding rectangle.

The second category affects text alignment in the y-direction:

- `TA_BASELINE` Aligns the point with the base line of the chosen font.

- `TA_BOTTOM` Aligns the point with the bottom of the bounding rectangle.

- `TA_TOP` Aligns the point with the top of the bounding rectangle. This is the default setting.

The third category determines whether the current position is updated when text is written:

- `TA_NOUPDATECP` Doesn't update the current position after each call to a text-output function. This is the default setting.

- `TA_UPDATECP` Updates the current x-position after each call to a text-output function. The new position is at the right side of the bounding rectangle for the text. When this flag is set, the coordinates specified in calls to the `TextOut` member function are ignored.

### Return Value

The previous text-alignment setting, if successful. The low-order byte contains the horizontal setting and the high-order byte contains the vertical setting; otherwise 0.

### Remarks

The `TextOut` and `ExtTextOut` member functions use these flags when positioning a string of text on a display or device. The flags specify the relationship between a specific point and a rectangle that bounds the text. The coordinates of this point are passed as parameters to the `TextOut` member function. The rectangle that bounds the text is formed by the adjacent character cells in the text string.

## <a name="settextcharacterextra"></a> `CDC::SetTextCharacterExtra`

Sets the amount of intercharacter spacing.

```
int SetTextCharacterExtra(int nCharExtra);
```

### Parameters

*`nCharExtra`*\
Specifies the amount of extra space (in logical units) to be added to each character. If the current mapping mode isn't `MM_TEXT`, *`nCharExtra`* is transformed and rounded to the nearest pixel.

### Return Value

The amount of the previous intercharacter spacing.

### Remarks

GDI adds this spacing to each character, including break characters, when it writes a line of text to the device context. The default value for the amount of intercharacter spacing is 0.

## <a name="settextcolor"></a> `CDC::SetTextColor`

Sets the text color to the specified color.

```
virtual COLORREF SetTextColor(COLORREF crColor);
```

### Parameters

*`crColor`*\
Specifies the color of the text as an RGB color value.

### Return Value

An RGB value for the previous text color.

### Remarks

The system uses this text color when writing text to this device context and also when converting bitmaps between color and monochrome device contexts.

If the device cannot represent the specified color, the system sets the text color to the nearest physical color. The background color for a character is specified by the `SetBkColor` and `SetBkMode` member functions.

### Example

  See the example for [`CWnd::OnCtlColor`](../../mfc/reference/cwnd-class.md#onctlcolor).

## <a name="settextjustification"></a> `CDC::SetTextJustification`

Adds space to the break characters in a string.

```
int SetTextJustification(
    int nBreakExtra,
    int nBreakCount);
```

### Parameters

*`nBreakExtra`*\
Specifies the total extra space to be added to the line of text (in logical units). If the current mapping mode isn't `MM_TEXT`, the value given by this parameter is converted to the current mapping mode and rounded to the nearest device unit.

*`nBreakCount`*\
Specifies the number of break characters in the line.

### Return Value

One if the function is successful; otherwise 0.

### Remarks

An application can use the `GetTextMetrics` member functions to retrieve a font's break character.

After the `SetTextJustification` member function is called, a call to a text-output function (such as `TextOut`) distributes the specified extra space evenly among the specified number of break characters. The break character is usually the space character (ASCII 32), but may be defined by a font as some other character.

The member function `GetTextExtent` is typically used with `SetTextJustification`. `GetTextExtent` computes the width of a given line before alignment. An application can determine how much space to specify in the *`nBreakExtra`* parameter by subtracting the value returned by `GetTextExtent` from the width of the string after alignment.

The `SetTextJustification` function can be used to align a line that contains multiple runs in different fonts. In this case, the line must be created piecemeal by aligning and writing each run separately.

Because rounding errors can occur during alignment, the system keeps a running error term that defines the current error. When aligning a line that contains multiple runs, `GetTextExtent` automatically uses this error term when it computes the extent of the next run. This allows the text-output function to blend the error into the new run.

After each line has been aligned, this error term must be cleared to prevent it from being incorporated into the next line. The term can be cleared by calling `SetTextJustification` with *`nBreakExtra`* set to 0.

## <a name="setviewportext"></a> `CDC::SetViewportExt`

Sets the x- and y-extents of the viewport of the device context.

```
virtual CSize SetViewportExt(
    int cx,
    int cy);

CSize SetViewportExt(SIZE size);
```

### Parameters

*`cx`*\
Specifies the x-extent of the viewport (in device units).

*`cy`*\
Specifies the y-extent of the viewport (in device units).

*`size`*\
Specifies the x- and y-extents of the viewport (in device units).

### Return Value

The previous extents of the viewport as a [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object. When an error occurs, the x- and y-coordinates of the returned `CSize` object are both set to 0.

### Remarks

The viewport, along with the device-context window, defines how GDI maps points in the logical coordinate system to points in the coordinate system of the actual device. In other words, they define how GDI converts logical coordinates into device coordinates.

When the following mapping modes are set, calls to `SetWindowExt` and `SetViewportExt` are ignored:

|`MM_HIENGLISH`|`MM_LOMETRIC`|
|-------------------|------------------|
|`MM_HIMETRIC`|`MM_TEXT`|
|`MM_LOENGLISH`|`MM_TWIPS`|

When `MM_ISOTROPIC` mode is set, an application must call the `SetWindowExt` member function before it calls `SetViewportExt`.

### Example

  See the example for [`CView::OnPrepareDC`](../../mfc/reference/cview-class.md#onpreparedc).

## <a name="setviewportorg"></a> `CDC::SetViewportOrg`

Sets the viewport origin of the device context.

```
virtual CPoint SetViewportOrg(
    int x,
    int y);

CPoint SetViewportOrg(POINT point);
```

### Parameters

*`x`*\
Specifies the x-coordinate (in device units) of the origin of the viewport. The value must be within the range of the device coordinate system.

*`y`*\
Specifies the y-coordinate (in device units) of the origin of the viewport. The value must be within the range of the device coordinate system.

*`point`*\
Specifies the origin of the viewport. The values must be within the range of the device coordinate system. You can pass either a `POINT` structure or a `CPoint` object for this parameter.

### Return Value

The previous origin of the viewport (in device coordinates) as a `CPoint` object.

### Remarks

The viewport, along with the device-context window, defines how GDI maps points in the logical coordinate system to points in the coordinate system of the actual device. In other words, they define how GDI converts logical coordinates into device coordinates.

The viewport origin marks the point in the device coordinate system to which GDI maps the window origin, a point in the logical coordinate system specified by the `SetWindowOrg` member function. GDI maps all other points by following the same process required to map the window origin to the viewport origin. For example, all points in a circle around the point at the window origin will be in a circle around the point at the viewport origin. Similarly, all points in a line that passes through the window origin will be in a line that passes through the viewport origin.

### Example

  See the example for [`CView::OnPrepareDC`](../../mfc/reference/cview-class.md#onpreparedc).

## <a name="setwindowext"></a> `CDC::SetWindowExt`

Sets the x- and y-extents of the window associated with the device context.

```
virtual CSize SetWindowExt(
    int cx,
    int cy);

CSize SetWindowExt(SIZE size);
```

### Parameters

*`cx`*\
Specifies the x-extent (in logical units) of the window.

*`cy`*\
Specifies the y-extent (in logical units) of the window.

*`size`*\
Specifies the x- and y-extents (in logical units) of the window.

### Return Value

The previous extents of the window (in logical units) as a `CSize` object. If an error occurs, the x- and y-coordinates of the returned `CSize` object are both set to 0.

### Remarks

The window, along with the device-context viewport, defines how GDI maps points in the logical coordinate system to points in the device coordinate system.

When the following mapping modes are set, calls to `SetWindowExt` and `SetViewportExt` functions are ignored:

- `MM_HIENGLISH`

- `MM_HIMETRIC`

- `MM_LOENGLISH`

- `MM_LOMETRIC`

- `MM_TEXT`

- `MM_TWIPS`

When `MM_ISOTROPIC` mode is set, an application must call the `SetWindowExt` member function before calling `SetViewportExt`.

### Example

  See the example for [`CView::OnPrepareDC`](../../mfc/reference/cview-class.md#onpreparedc).

## <a name="setwindoworg"></a> `CDC::SetWindowOrg`

Sets the window origin of the device context.

```
CPoint SetWindowOrg(
    int x,
    int y);

CPoint SetWindowOrg(POINT point);
```

### Parameters

*`x`*\
Specifies the logical x-coordinate of the new origin of the window.

*`y`*\
Specifies the logical y-coordinate of the new origin of the window.

*`point`*\
Specifies the logical coordinates of the new origin of the window. You can pass either a `POINT` structure or a `CPoint` object for this parameter.

### Return Value

The previous origin of the window as a `CPoint` object.

### Remarks

The window, along with the device-context viewport, defines how GDI maps points in the logical coordinate system to points in the device coordinate system.

The window origin marks the point in the logical coordinate system from which GDI maps the viewport origin, a point in the device coordinate system specified by the `SetWindowOrg` function. GDI maps all other points by following the same process required to map the window origin to the viewport origin. For example, all points in a circle around the point at the window origin will be in a circle around the point at the viewport origin. Similarly, all points in a line that passes through the window origin will be in a line that passes through the viewport origin.

## <a name="setworldtransform"></a> `CDC::SetWorldTransform`

Sets a two-dimensional linear transformation between world space and page space for the specified device context. This transformation can be used to scale, rotate, shear, or translate graphics output.

```
BOOL SetWorldTransform(const XFORM& rXform);
```

### Parameters

*`rXform`*\
Reference to an [`XFORM`](/windows/win32/api/wingdi/ns-wingdi-xform) structure that contains the transformation data.

### Return Value

Returns a nonzero value on success.

Returns 0 on failure.

To get extended error information, call [`GetLastError`](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror).

### Remarks

This method wraps the Windows GDI function [`SetWorldTransform`](/windows/win32/api/wingdi/nf-wingdi-setworldtransform).

## <a name="startdoc"></a> `CDC::StartDoc`

Informs the device driver that a new print job is starting and that all subsequent `StartPage` and `EndPage` calls should be spooled under the same job until an `EndDoc` call occurs.

```
int StartDoc(LPDOCINFO lpDocInfo);
int StartDoc(LPCTSTR lpszDocName);
```

### Parameters

*`lpDocInfo`*\
Points to a [`DOCINFO`](/windows/win32/api/wingdi/ns-wingdi-docinfow) structure containing the name of the document file and the name of the output file.

*`lpszDocName`*\
Pointer to a string containing the name of the document file.

### Return Value

If the function succeeds, the return value is greater than zero. This value is the print job identifier for the document.

If the function fails, the return value is less than or equal to zero.

### Remarks

This ensures that documents longer than one page won't be interspersed with other jobs.

For Windows versions 3.1 and later, this function replaces the `STARTDOC` printer escape. Using this function ensures that documents containing more than one page aren't interspersed with other print jobs.

`StartDoc` shouldn't be used inside metafiles.

### Example

This code fragment gets the default printer, opens a print job, and spools one page with "Hello, World!" on it. Because the text printed by this code isn't scaled to the printer's logical units, the output text may be in such small letters that the result is unreadable. The CDC scaling functions, such as `SetMapMode`, `SetViewportOrg`, and `SetWindowExt`, can be used to fix the scaling.

[!code-cpp[NVC_MFCDocView#41](../../mfc/codesnippet/cpp/cdc-class_13.cpp)]

## <a name="startpage"></a> `CDC::StartPage`

Call this member function to prepare the printer driver to receive data.

```
int StartPage();
```

### Return Value

Greater than or equal to 0 if the function is successful, or a negative value if an error occurred.

### Remarks

`StartPage` supersedes the `NEWFRAME` and `BANDINFO` escapes.

For an overview of the sequence of printing calls, see the [`StartDoc`](#startdoc) member function.

The system disables the `ResetDC` member function between calls to `StartPage` and `EndPage`.

### Example

  See the example for [`CDC::StartDoc`](#startdoc).

## <a name="stretchblt"></a> `CDC::StretchBlt`

Copies a bitmap from a source rectangle into a destination rectangle, stretching or compressing the bitmap if necessary to fit the dimensions of the destination rectangle.

```
BOOL StretchBlt(
    int x,
    int y,
    int nWidth,
    int nHeight,
    CDC* pSrcDC,
    int xSrc,
    int ySrc,
    int nSrcWidth,
    int nSrcHeight,
    DWORD dwRop);
```

### Parameters

*`x`*\
Specifies the x-coordinate (in logical units) of the upper-left corner of the destination rectangle.

*`y`*\
Specifies the y-coordinate (in logical units) of the upper-left corner of the destination rectangle.

*`nWidth`*\
Specifies the width (in logical units) of the destination rectangle.

*`nHeight`*\
Specifies the height (in logical units) of the destination rectangle.

*`pSrcDC`*\
Specifies the source device context.

*`xSrc`*\
Specifies the x-coordinate (in logical units) of the upper-left corner of the source rectangle.

*`ySrc`*\
Specifies the y-coordinate (in logical units) of the upper-left corner of the source rectangle.

*`nSrcWidth`*\
Specifies the width (in logical units) of the source rectangle.

*`nSrcHeight`*\
Specifies the height (in logical units) of the source rectangle.

*`dwRop`*\
Specifies the raster operation to be performed. Raster operation codes define how GDI combines colors in output operations that involve a current brush, a possible source bitmap, and a destination bitmap. This parameter may be one of the following values:

- `BLACKNESS` Turns all output black.

- `DSTINVERT` Inverts the destination bitmap.

- `MERGECOPY` Combines the pattern and the source bitmap using the Boolean **AND** operator.

- `MERGEPAINT` Combines the inverted source bitmap with the destination bitmap using the Boolean **OR** operator.

- `NOTSRCCOPY` Copies the inverted source bitmap to the destination.

- `NOTSRCERASE` Inverts the result of combining the destination and source bitmaps using the Boolean **OR** operator.

- `PATCOPY` Copies the pattern to the destination bitmap.

- `PATINVERT` Combines the destination bitmap with the pattern using the Boolean **XOR** operator.

- `PATPAINT` Combines the inverted source bitmap with the pattern using the Boolean **OR** operator. Combines the result of this operation with the destination bitmap using the Boolean **OR** operator.

- `SRCAND` Combines pixels of the destination and source bitmaps using the Boolean **AND** operator.

- `SRCCOPY` Copies the source bitmap to the destination bitmap.

- `SRCERASE` Inverts the destination bitmap and combines the result with the source bitmap using the Boolean **AND** operator.

- `SRCINVERT` Combines pixels of the destination and source bitmaps using the Boolean **XOR** operator.

- `SRCPAINT` Combines pixels of the destination and source bitmaps using the Boolean **OR** operator.

- `WHITENESS` Turns all output white.

### Return Value

Nonzero if the bitmap is drawn; otherwise 0.

### Remarks

The function uses the stretching mode of the destination device context (set by `SetStretchBltMode`) to determine how to stretch or compress the bitmap.

The `StretchBlt` function moves the bitmap from the source device given by *`pSrcDC`* to the destination device represented by the device-context object whose member function is being called. The *`xSrc`*, *`ySrc`*, *`nSrcWidth`*, and *`nSrcHeight`* parameters define the upper-left corner and dimensions of the source rectangle. The *`x`*, *`y`*, *`nWidth`*, and *`nHeight`* parameters give the upper-left corner and dimensions of the destination rectangle. The raster operation specified by *`dwRop`* defines how the source bitmap and the bits already on the destination device are combined.

The `StretchBlt` function creates a mirror image of a bitmap if the signs of the *`nSrcWidth`* and *`nWidth`* or *`nSrcHeight`* and *`nHeight`* parameters differ. If *`nSrcWidth`* and *`nWidth`* have different signs, the function creates a mirror image of the bitmap along the x-axis. If *`nSrcHeight`* and *`nHeight`* have different signs, the function creates a mirror image of the bitmap along the y-axis.

The `StretchBlt` function stretches or compresses the source bitmap in memory and then copies the result to the destination. If a pattern is to be merged with the result, it isn't merged until the stretched source bitmap is copied to the destination. If a brush is used, it's the selected brush in the destination device context. The destination coordinates are transformed according to the destination device context; the source coordinates are transformed according to the source device context.

If the destination, source, and pattern bitmaps don't have the same color format, `StretchBlt` converts the source and pattern bitmaps to match the destination bitmaps. The foreground and background colors of the destination device context are used in the conversion.

If `StretchBlt` must convert a monochrome bitmap to color, it sets white bits (1) to the background color and black bits (0) to the foreground color. To convert color to monochrome, it sets pixels that match the background color to white (1) and sets all other pixels to black (0). The foreground and background colors of the device context with color are used.

Not all devices support the `StretchBlt` function. To determine whether a device supports `StretchBlt`, call the `GetDeviceCaps` member function with the `RASTERCAPS` index and check the return value for the `RC_STRETCHBLT` flag.

## <a name="strokeandfillpath"></a> `CDC::StrokeAndFillPath`

Closes any open figures in a path, strokes the outline of the path by using the current pen, and fills its interior by using the current brush.

```
BOOL StrokeAndFillPath();
```

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The device context must contain a closed path. The `StrokeAndFillPath` member function has the same effect as closing all the open figures in the path, and stroking and filling the path separately, except that the filled region won't overlap the stroked region even if the pen is wide.

## <a name="strokepath"></a> `CDC::StrokePath`

Renders the specified path by using the current pen.

```
BOOL StrokePath();
```

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

The device context must contain a closed path.

## <a name="tabbedtextout"></a> `CDC::TabbedTextOut`

Call this member function to write a character string at the specified location, expanding tabs to the values specified in the array of tab-stop positions.

```
virtual CSize TabbedTextOut(
    int x,
    int y,
    LPCTSTR lpszString,
    int nCount,
    int nTabPositions,
    LPINT lpnTabStopPositions,
    int nTabOrigin);

CSize TabbedTextOut(
    int x,
    int y,
    const CString& str,
    int nTabPositions,
    LPINT lpnTabStopPositions,
    int nTabOrigin);
```

### Parameters

*`x`*\
Specifies the logical x-coordinate of the starting point of the string.

*`y`*\
Specifies the logical y-coordinate of the starting point of the string.

*`lpszString`*\
Points to the character string to draw. You can pass either a pointer to an array of characters or a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object for this parameter.

*`nCount`*\
Specifies the [length of the string](/windows/win32/gdi/specifying-length-of-text-output-string) pointed to by *`lpszString`*.

*`nTabPositions`*\
Specifies the number of values in the array of tab-stop positions.

*`lpnTabStopPositions`*\
Points to an array containing the tab-stop positions (in logical units). The tab stops must be sorted in increasing order; the smallest x-value should be the first item in the array.

*`nTabOrigin`*\
Specifies the x-coordinate of the starting position from which tabs are expanded (in logical units).

*`str`*\
A `CString` object that contains the specified characters.

### Return Value

The dimensions of the string (in logical units) as a `CSize` object.

### Remarks

Text is written in the currently selected font. If *`nTabPositions`* is 0 and *`lpnTabStopPositions`* is `NULL`, tabs are expanded to eight times the average character width.

If *`nTabPositions`* is 1, the tab stops are separated by the distance specified by the first value in the *`lpnTabStopPositions`* array. If the *`lpnTabStopPositions`* array contains more than one value, a tab stop is set for each value in the array, up to the number specified by *`nTabPositions`*. The *`nTabOrigin`* parameter allows an application to call the `TabbedTextOut` function several times for a single line. If the application calls the function more than once with the *`nTabOrigin`* set to the same value each time, the function expands all tabs relative to the position specified by *`nTabOrigin`*.

By default, the current position isn't used or updated by the function. If an application needs to update the current position when it calls the function, the application can call the [`SetTextAlign`](#settextalign) member function with *`nFlags`* set to `TA_UPDATECP`. When this flag is set, Windows ignores the *`x`* and *`y`* parameters on subsequent calls to `TabbedTextOut`, using the current position instead.

## <a name="textout"></a> `CDC::TextOut`

Writes a character string at the specified location using the currently selected font.

```
virtual BOOL TextOut(
    int x,
    int y,
    LPCTSTR lpszString,
    int nCount);

BOOL TextOut(
    int x,
    int y,
    const CString& str);
```

### Parameters

*`x`*\
Specifies the logical x-coordinate of the starting point of the text.

*`y`*\
Specifies the logical y-coordinate of the starting point of the text.

*`lpszString`*\
Points to the character string to be drawn.

*`nCount`*\
Specifies the number of characters in the string.

*`str`*\
A `CString` object that contains the characters to be drawn.

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

Character origins are at the upper-left corner of the character cell. By default, the current position isn't used or updated by the function.

If an application needs to update the current position when it calls `TextOut`, the application can call the `SetTextAlign` member function with *`nFlags`* set to `TA_UPDATECP`. When this flag is set, Windows ignores the *`x`* and *`y`* parameters on subsequent calls to `TextOut`, using the current position instead.

### Example

  See the example for [`CDC::BeginPath`](#beginpath).

## <a name="transparentblt"></a> `CDC::TransparentBlt`

Call this member function to transfer a bit-block of the color data, which corresponds to a rectangle of pixels from the specified source device context, into a destination device context.

```
BOOL TransparentBlt(
    int xDest,
    int yDest,
    int nDestWidth,
    int nDestHeight,
    CDC* pSrcDC,
    int xSrc,
    int ySrc,
    int nSrcWidth,
    int nSrcHeight,
    UINT clrTransparent);
```

### Parameters

*`xDest`*\
Specifies the x-coordinate, in logical units, of the upper-left corner of the destination rectangle.

*`yDest`*\
Specifies the y-coordinate, in logical units, of the upper-left corner of the destination rectangle.

*`nDestWidth`*\
Specifies the width, in logical units, of the destination rectangle.

*`nDestHeight`*\
Specifies the height, in logical units, of the destination rectangle.

*`pSrcDC`*\
Pointer to the source device context.

*`xSrc`*\
Specifies the x-coordinate, in logical units, of the source rectangle.

*`ySrc`*\
Specifies the y-coordinate, in logical units, of the source rectangle.

*`nSrcWidth`*\
Specifies the width, in logical units, of the source rectangle.

*`nSrcHeight`*\
Specifies the height, in logical units, of the source rectangle.

*`clrTransparent`*\
The RGB color in the source bitmap to treat as transparent.

### Return Value

`TRUE` if successful; otherwise `FALSE`.

### Remarks

`TransparentBlt` allows for transparency; that is, the RGB color indicated by *`clrTransparent`* is rendered transparent for the transfer.

For more information, see [`TransparentBlt`](/windows/win32/api/wingdi/nf-wingdi-transparentblt) in the Windows SDK.

## <a name="updatecolors"></a> `CDC::UpdateColors`

Updates the client area of the device context by matching the current colors in the client area to the system palette on a pixel-by-pixel basis.

```cpp
void UpdateColors();
```

### Remarks

An inactive window with a realized logical palette may call `UpdateColors` as an alternative to redrawing its client area when the system palette changes.

For more information about using color palettes, see [`UpdateColors`](/windows/win32/api/wingdi/nf-wingdi-updatecolors) in the Windows SDK.

The `UpdateColors` member function typically updates a client area faster than redrawing the area. However, because the function performs the color translation based on the color of each pixel before the system palette changed, each call to this function results in the loss of some color accuracy.

## <a name="widenpath"></a> `CDC::WidenPath`

Redefines the current path as the area that would be painted if the path were stroked using the pen currently selected into the device context.

```
BOOL WidenPath();
```

### Return Value

Nonzero if the function is successful; otherwise 0.

### Remarks

This function is successful only if the current pen is a geometric pen created by the second version of `CreatePen` member function, or if the pen is created with the first version of `CreatePen` and has a width, in device units, of greater than 1. The device context must contain a closed path. Any Bzier curves in the path are converted to sequences of straight lines approximating the widened curves. As such, no Bzier curves remain in the path after `WidenPath` is called.

## See also

[`CObject` Class](../../mfc/reference/cobject-class.md)\
[Hierarchy Chart](../../mfc/hierarchy-chart.md)\
[`CPaintDC` Class](../../mfc/reference/cpaintdc-class.md)\
[`CWindowDC` Class](../../mfc/reference/cwindowdc-class.md)\
[`CClientDC` Class](../../mfc/reference/cclientdc-class.md)\
[`CMetaFileDC` Class](../../mfc/reference/cmetafiledc-class.md)