`CDC` 类

项目
10/15/2023

定义设备上下文对象的类。

语法

class CDC : public CObject

成员

公共构造函数

名称	描述
`CDC::CDC`	构造 `CDC` 对象。

公共方法

名称	描述
`CDC::AbortDoc`	终止当前打印作业，从而清除自上次调用 `StartDoc` 成员函数以来应用程序写入设备的所有内容。
`CDC::AbortPath`	闭合并放弃设备上下文中的任何路径。
`CDC::AddMetaFileComment`	将注释从缓冲区复制到指定的增强格式图元文件中。
`CDC::AlphaBlend`	显示具有透明或半透明像素的位图。
`CDC::AngleArc`	绘制线段和弧线，并将当前位置移动到弧线的终点。
`CDC::Arc`	绘制椭圆弧线。
`CDC::ArcTo`	绘制椭圆弧线。此函数类似于 `Arc`，但当前位置已更新。
`CDC::Attach`	将 Windows 设备上下文附加到此 `CDC` 对象。
`CDC::BeginPath`	在设备上下文中开放一个路径括号。
`CDC::BitBlt`	从指定的设备上下文复制位图。
`CDC::Chord`	绘制弦形（由椭圆和线段的交点界定的封闭图形）。
`CDC::CloseFigure`	闭合路径中开放的图形。
`CDC::CreateCompatibleDC`	创建与另一个设备上下文兼容的内存设备上下文。可以使用它来准备内存中的图像。
`CDC::CreateDC`	为特定设备创建设备上下文。
`CDC::CreateIC`	为特定设备创建信息上下文。这提供了一种无需创建设备上下文即可快速获取设备相关信息的方法。
`CDC::DeleteDC`	删除与此 `CDC` 对象关联的 Windows 设备上下文。
`CDC::DeleteTempMap`	由 `CWinApp` 空闲时间处理程序调用，以删除由 `FromHandle` 创建的任何临时 `CDC` 对象。还分离设备上下文。
`CDC::Detach`	从此 `CDC` 对象中分离 Windows 设备上下文。
`CDC::DPtoHIMETRIC`	将设备单元转换为 `HIMETRIC` 单元。
`CDC::DPtoLP`	将设备单元转换为逻辑单元。
`CDC::Draw3dRect`	绘制三维矩形。
`CDC::DrawDragRect`	在拖动矩形时擦除并重新绘制它。
`CDC::DrawEdge`	绘制矩形的边缘。
`CDC::DrawEscape`	访问不能通过图形设备接口 (GDI) 直接获得的视频显示的绘图功能。
`CDC::DrawFocusRect`	以用于指示焦点的样式绘制矩形。
`CDC::DrawFrameControl`	绘制框架控件。
`CDC::DrawIcon`	绘制图标。
`CDC::DrawState`	显示图像并应用视觉效果来指示状态。
`CDC::DrawText`	在指定的矩形中绘制格式化文本。
`CDC::DrawTextEx`	使用其他格式在指定的矩形中绘制格式化文本。
`CDC::Ellipse`	绘制椭圆形。
`CDC::EndDoc`	结束由 `StartDoc` 成员函数启动的打印作业。
`CDC::EndPage`	通知设备驱动程序页面即将结束。
`CDC::EndPath`	闭合路径括号，并选择括号定义的路径进入设备上下文。
`CDC::EnumObjects`	枚举设备上下文中可用的触笔和画笔。
`CDC::Escape`	允许应用程序通过 GDI 访问无法直接从特定设备获取的设施。还允许访问 Windows 转义函数。应用程序进行的转义调用被转换并发送到设备驱动程序。
`CDC::ExcludeClipRect`	创建一个由现有剪切区域减去指定矩形组成的新剪切区域。
`CDC::ExcludeUpdateRgn`	通过从剪切区域中排除窗口中的更新区域来防止在窗口的无效区域内绘图。
`CDC::ExtFloodFill`	使用当前画笔填充区域。提供比 `CDC::FloodFill` 成员函数更大的灵活性。
`CDC::ExtTextOut`	使用当前选择的字体在矩形区域内写入字符串。
`CDC::FillPath`	闭合当前路径中所有开放的图形，并使用当前画笔和多边形填充模式填充路径的内部。
`CDC::FillRect`	使用特定画笔填充给定的矩形。
`CDC::FillRgn`	使用指定的画笔填充特定区域。
`CDC::FillSolidRect`	使用纯色填充矩形。
`CDC::FlattenPath`	将所选路径中的任何曲线转换为当前设备上下文，并将每个曲线转换为一系列线条。
`CDC::FloodFill`	使用当前画笔填充区域。
`CDC::FrameRect`	在矩形周围绘制边框。
`CDC::FrameRgn`	使用画笔在特定区域周围绘制边框。
`CDC::FromHandle`	在提供了设备上下文的句柄时返回指向 `CDC` 对象的指针。如果 `CDC` 对象未附加到该句柄，则会创建并附加一个临时 `CDC` 对象。
`CDC::GetArcDirection`	返回设备上下文的当前弧线方向。
`CDC::GetAspectRatioFilter`	检索当前纵横比筛选器的设置。
`CDC::GetBkColor`	检索当前背景色。
`CDC::GetBkMode`	检索后台模式。
`CDC::GetBoundsRect`	返回指定设备上下文的当前累积边框。
`CDC::GetBrushOrg`	检索当前画笔的原点。
`CDC::GetCharABCWidths`	从当前字体检索给定范围内连续字符的宽度（以逻辑单元表示）。
`CDC::GetCharABCWidthsI`	从当前 TrueType 字体检索指定范围内连续字形索引的宽度（以逻辑单元表示）。
`CDC::GetCharacterPlacement`	检索有关字符串的各种信息。
`CDC::GetCharWidth`	从当前字体检索给定范围内连续字符的小数宽度。
`CDC::GetCharWidthI`	从当前字体检索指定范围内连续字形索引的宽度（以逻辑坐标表示）。
`CDC::GetClipBox`	检索围绕当前剪切边界的最紧密边框的尺寸。
`CDC::GetColorAdjustment`	检索设备上下文的颜色调整值。
`CDC::GetCurrentBitmap`	返回指向当前所选 `CBitmap` 对象的指针。
`CDC::GetCurrentBrush`	返回指向当前所选 `CBrush` 对象的指针。
`CDC::GetCurrentFont`	返回指向当前所选 `CFont` 对象的指针。
`CDC::GetCurrentPalette`	返回指向当前所选 `CPalette` 对象的指针。
`CDC::GetCurrentPen`	返回指向当前所选 `CPen` 对象的指针。
`CDC::GetCurrentPosition`	检索触笔的当前位置（以逻辑坐标表示）。
`CDC::GetDCBrushColor`	检索当前画笔的颜色。
`CDC::GetDCPenColor`	检索当前的钢笔颜色。
`CDC::GetDeviceCaps`	检索有关给定显示设备功能的指定类型的设备特定信息。
`CDC::GetFontData`	从可缩放字体文件检索字体指标信息。通过指定字体文件的偏移量和要返回的信息的长度来识别要检索的信息。
`CDC::GetFontLanguageInfo`	返回有关指定显示上下文的当前选定字体的信息。
`CDC::GetGlyphOutline`	检索当前字体中轮廓字符的轮廓曲线或位图。
`CDC::GetGraphicsMode`	检索指定设备上下文的当前图形模式。
`CDC::GetHalftoneBrush`	检索半色调画笔。
`CDC::GetKerningPairs`	检索当前在指定设备上下文中选择的字体的字符间距调整对。
`CDC::GetLayout`	检索设备上下文 (DC) 的布局。布局可以是从左到右（默认），也可以是从右到左（镜像）。
`CDC::GetMapMode`	检索当前映射模式。
`CDC::GetMiterLimit`	返回设备上下文的斜接限制。
`CDC::GetNearestColor`	检索与给定设备可以表示的指定逻辑颜色最接近的逻辑颜色。
`CDC::GetOutlineTextMetrics`	检索 TrueType 字体的字体指标信息。
`CDC::GetOutputCharWidth`	使用输出设备上下文从当前字体检索连续字符组中各个字符的宽度。
`CDC::GetOutputTabbedTextExtent`	计算输出设备上下文中字符串的宽度和高度。
`CDC::GetOutputTextExtent`	使用当前字体计算输出设备上下文中一行文本的宽度和高度以确定尺寸。
`CDC::GetOutputTextMetrics`	从输出设备上下文中检索当前字体的指标。
`CDC::GetPath`	检索定义线端点的坐标，以及在设备上下文中选择的路径中找到的曲线的控制点。
`CDC::GetPixel`	检索指定点处像素的 RGB 颜色值。
`CDC::GetPolyFillMode`	检索当前多边形填充模式。
`CDC::GetROP2`	检索当前绘图模式。
`CDC::GetSafeHdc`	返回输出设备上下文 `CDC::m_hDC`。
`CDC::GetStretchBltMode`	检索当前位图拉伸模式。
`CDC::GetTabbedTextExtent`	计算属性设备上下文中字符串的宽度和高度。
`CDC::GetTextAlign`	检索文本对齐标志。
`CDC::GetTextCharacterExtra`	检索字符间间距的当前设置。
`CDC::GetTextColor`	检索当前的文本颜色。
`CDC::GetTextExtent`	使用当前字体计算属性设备上下文中一行文本的宽度和高度以确定尺寸。
`CDC::GetTextExtentExPointI`	检索指定字符串中适合指定空间的字符数，并用其中每个字符的文本范围填充数组。
`CDC::GetTextExtentPointI`	检索指定字形索引数组的宽度和高度。
`CDC::GetTextFace`	将当前字体的字样名称作为以 null 结尾的字符串复制到缓冲区中。
`CDC::GetTextMetrics`	从属性设备上下文中检索当前字体的指标。
`CDC::GetViewportExt`	检索视区的 x 范围和 y 范围。
`CDC::GetViewportOrg`	检索视区原点的 x 坐标和 y 坐标。
`CDC::GetWindow`	返回与显示设备上下文关联的窗口。
`CDC::GetWindowExt`	检索关联窗口的 x 范围和 y 范围。
`CDC::GetWindowOrg`	检索关联窗口的原点的 x 坐标和 y 坐标。
`CDC::GetWorldTransform`	检索当前世界空间到页面空间的转换。
`CDC::GradientFill`	使用渐变颜色填充矩形和三角形结构。
`CDC::GrayString`	在给定位置绘制变暗（灰色）文本。
`CDC::HIMETRICtoDP`	将 HIMETRIC 单元转换为设备单元。
`CDC::HIMETRICtoLP`	将 HIMETRIC 单元转换为逻辑单元。
`CDC::IntersectClipRect`	通过形成当前区域和矩形的交集来创建新的剪切区域。
`CDC::InvertRect`	反转矩形的内容。
`CDC::InvertRgn`	反转区域中的颜色。
`CDC::IsPrinting`	确定设备上下文是否用于打印。
`CDC::LineTo`	从当前位置绘制一条线直到（但不包括）一个点。
`CDC::LPtoDP`	将逻辑单元转换为设备单元。
`CDC::LPtoHIMETRIC`	将逻辑单元转换为 HIMETRIC 单元。
`CDC::MaskBlt`	使用给定的蒙板和光栅操作组合源位图和目标位图的颜色数据。
`CDC::ModifyWorldTransform`	使用指定模式更改设备上下文的世界转换。
`CDC::MoveTo`	移动当前位置。
`CDC::OffsetClipRgn`	移动给定设备的剪切区域。
`CDC::OffsetViewportOrg`	相对于当前视区原点的坐标修改视区原点。
`CDC::OffsetWindowOrg`	相对于当前窗口原点的坐标修改窗口原点。
`CDC::PaintRgn`	使用所选画笔填充区域。
`CDC::PatBlt`	创建位模式。
`CDC::Pie`	绘制饼形楔形。
`CDC::PlayMetaFile`	在给定设备上播放指定图元文件的内容。 `PlayMetaFile` 的增强版本显示存储在给定增强格式图元文件中的图片。可以任意次数播放图元文件。
`CDC::PlgBlt`	执行颜色数据位的位块传输，从源设备上下文中的指定矩形传输到给定设备上下文中的指定平行四边形。
`CDC::PolyBezier`	绘制一条或多条贝塞尔曲线。既不使用也不更新当前位置。
`CDC::PolyBezierTo`	绘制一条或多条贝塞尔曲线，并将当前位置移动到最后一条贝塞尔曲线的终点。
`CDC::PolyDraw`	绘制一组线段和贝塞尔曲线。此函数更新当前位置。
`CDC::Polygon`	绘制由通过线连接的两个或更多点（顶点）组成的多边形。
`CDC::Polyline`	绘制一组连接指定点的线段。
`CDC::PolylineTo`	绘制一条或多条直线，并将当前位置移动到最后一条线的终点。
`CDC::PolyPolygon`	创建两个或更多使用当前多边形填充模式填充的多边形。多边形可能不相交，也可能重叠。
`CDC::PolyPolyline`	绘制多个系列连接的线段。此函数既不使用也不更新当前位置。
`CDC::PtVisible`	指定给定点是否在剪切区域中。
`CDC::RealizePalette`	将当前逻辑调色板中的调色板条目映射到系统调色板。
`CDC::Rectangle`	使用当前触笔绘制一个矩形并使用当前画笔进行填充。
`CDC::RectVisible`	确定给定矩形的任何部分是否位于剪切区域内。
`CDC::ReleaseAttribDC`	发布属性设备上下文 `m_hAttribDC`。
`CDC::ReleaseOutputDC`	发布输出设备上下文 `m_hDC`。
`CDC::ResetDC`	更新 `m_hAttribDC` 设备上下文。
`CDC::RestoreDC`	将设备上下文恢复到使用 `SaveDC` 保存的先前状态。
`CDC::RoundRect`	使用当前触笔绘制一个带圆角的矩形，并使用当前画笔进行填充。
`CDC::SaveDC`	保存设备上下文的当前状态。
`CDC::ScaleViewportExt`	相对于当前值修改视区范围。
`CDC::ScaleWindowExt`	相对于当前值修改窗口范围。
`CDC::ScrollDC`	水平和垂直滚动一个位矩形。
`CDC::SelectClipPath`	选择当前路径作为设备上下文的剪切区域，使用指定的模式将新区域与任何现有剪切区域组合。
`CDC::SelectClipRgn`	使用指定的模式将给定区域与当前剪切区域组合在一起。
`CDC::SelectObject`	选择 GDI 绘图对象，例如触笔。
`CDC::SelectPalette`	选择逻辑调色板。
`CDC::SelectStockObject`	选择 Windows 提供的预定义的常用笔、画笔或字体之一。
`CDC::SetAbortProc`	如果必须中止打印作业，则设置 Windows 调用的程序员提供的回调函数。
`CDC::SetArcDirection`	设置要用于弧线和矩形函数的绘图方向。
`CDC::SetAttribDC`	设置属性设备上下文 `m_hAttribDC`。
`CDC::SetBkColor`	设置当前背景色。
`CDC::SetBkMode`	设置背景模式。
`CDC::SetBoundsRect`	控制指定设备上下文的边框信息的累积。
`CDC::SetBrushOrg`	指定选择到设备上下文中的下一个画笔的原点。
`CDC::SetColorAdjustment`	使用指定值设置设备上下文的颜色调整值。
`CDC::SetDCBrushColor`	设置当前的画笔颜色。
`CDC::SetDCPenColor`	设置当前的触笔颜色。
`CDC::SetGraphicsMode`	设置指定设备上下文的当前图形模式。
`CDC::SetLayout`	更改设备上下文 (DC) 的布局。
`CDC::SetMapMode`	设置当前映射模式。
`CDC::SetMapperFlags`	更改字体映射器在将逻辑字体映射到物理字体时使用的算法。
`CDC::SetMiterLimit`	设置设备上下文的斜角连接长度限制。
`CDC::SetOutputDC`	设置输出设备上下文 `m_hDC`。
`CDC::SetPixel`	将指定点处的像素设置为最接近指定颜色的值。
`CDC::SetPixelV`	将指定坐标处的像素设置为最接近指定颜色的值。 `SetPixelV` 比 `SetPixel` 快，因为它不需要返回绘制的点的颜色值。
`CDC::SetPolyFillMode`	设置多边形填充模式。
`CDC::SetROP2`	设置当前绘图模式。
`CDC::SetStretchBltMode`	设置位图拉伸模式。
`CDC::SetTextAlign`	设置文本对齐标志。
`CDC::SetTextCharacterExtra`	设置字符间距量。
`CDC::SetTextColor`	设置文本颜色。
`CDC::SetTextJustification`	向字符串中的中断字符添加空格。
`CDC::SetViewportExt`	设置视区的 x 范围和 y 范围。
`CDC::SetViewportOrg`	设置视区原点。
`CDC::SetWindowExt`	设置关联窗口的 x 范围和 y 范围。
`CDC::SetWindowOrg`	设置设备上下文的窗口原点。
`CDC::SetWorldTransform`	设置当前世界空间到页面空间的转换。
`CDC::StartDoc`	通知设备驱动程序新打印作业正在启动。
`CDC::StartPage`	通知设备驱动程序新页面正在启动。
`CDC::StretchBlt`	将位图从源矩形和设备移动到目标矩形，必要时可拉伸或压缩位图以符合目标矩形的尺寸。
`CDC::StrokeAndFillPath`	闭合路径中所有开放的图形，使用当前触笔绘制路径轮廓，并使用当前画笔填充路径内部。
`CDC::StrokePath`	使用当前触笔呈现指定的路径。
`CDC::TabbedTextOut`	在指定位置写入字符串，将制表符扩展到制表位位置数组中指定的值。
`CDC::TextOut`	使用当前选定的字体在指定位置写入字符串。
`CDC::TransparentBlt`	将颜色数据的位块从指定的源设备上下文传输到目标设备上下文，在传输中呈现指定的颜色透明。
`CDC::UpdateColors`	通过将工作区中每一个像数的当前颜色与系统调色板匹配来更新设备上下文的工作区。
`CDC::WidenPath`	将当前路径重新定义为：使用当前选择的触笔在设备上下文中描绘路径时将绘制的区域。

公共运算符

“属性”	描述
`CDC::operator HDC`	检索设备上下文的句柄。

公共数据成员

“属性”	描述
`CDC::m_hAttribDC`	此 `CDC` 对象使用的属性设备上下文。
`CDC::m_hDC`	此 `CDC` 对象使用的输出设备上下文。

备注

CDC 对象提供用于处理设备上下文（例如显示器或打印机）的成员函数，以及用于处理与窗口的工作区相关联的显示上下文的成员。

通过 CDC 对象的成员函数进行所有绘图。该类提供了用于设备上下文操作、使用绘图工具、类型安全的图形设备接口 (GDI) 对象选择以及使用颜色和调色板的成员函数。它还提供了用于获取和设置绘图属性、映射、使用视区、使用窗口范围、转换坐标、使用区域、剪切、绘制线条以及绘制简单形状、椭圆形和多边形的成员函数。还提供了用于绘制文本、处理字体、使用打印机转义、滚动和播放图元文件的成员函数。

若要使用 CDC 对象，请构造它，然后调用它的成员函数，这些函数与使用设备上下文的 Windows 函数并行。

注意

在 Windows 95/98 下，所有屏幕坐标都限制为 16 位。因此，传递给 CDC 成员函数的 int 必须位于 -32768 到 32767 的范围内。

对于特定用途，Microsoft 基础类库提供了几个派生自 CDC 的类。 CPaintDC 封装对 BeginPaint 和 EndPaint 的调用。 CClientDC 管理与窗口的工作区关联的显示上下文。 CWindowDC 管理与整个窗口关联的显示上下文，其中包括其框架和控件。 CMetaFileDC 将设备上下文与图元文件相关联。

CDC 提供了两个成员函数 GetLayout 和 SetLayout，用于反转设备上下文的布局，该布局不会从窗口继承其布局。对于为区域性（如阿拉伯语或希伯来语，在这些语言中字符布局不是欧洲标准）编写的应用程序来说，这种从右到左方向是必需的。

CDC 包含两个设备上下文 m_hDC 和 m_hAttribDC，它们在创建 CDC 对象时引用同一设备。 CDC 将所有输出 GDI 调用定向到 m_hDC，并将大多数属性 GDI 调用定向到 m_hAttribDC。（属性调用的示例是 GetTextColor，而 SetTextColor 是输出调用。）

例如，该框架使用这两个设备上下文来实现一个 CMetaFileDC 对象，该对象将在从物理设备读取属性的同时将输出发送到图元文件。打印预览以类似的方式在框架中实现。还可以在特定于应用程序的代码中以类似的方式使用这两个设备上下文。

有时可能需要来自 m_hDC 和 m_hAttribDC 设备上下文的文本指标信息。以下函数对提供此功能：

使用 m_hAttribDC	使用 m_hDC
`GetTextExtent`	`GetOutputTextExtent`
`GetTabbedTextExtent`	`GetOutputTabbedTextExtent`
`GetTextMetrics`	`GetOutputTextMetrics`
`GetCharWidth`	`GetOutputCharWidth`

有关 CDC 的详细信息，请参阅设备上下文。

继承层次结构

CObject

CDC

要求

标头afxwin.h：

`CDC::AbortDoc`

终止当前打印作业，并清除自上次调用 StartDoc 成员函数以来应用程序写入设备的所有内容。

int AbortDoc();

返回值

如果成功，则为大于或等于 0 的值；如果发生错误，则为负值。以下列表显示了常见错误值及其含义：

SP_ERROR 常规错误。
SP_OUTOFDISK 当前没有足够的磁盘空间可用于后台处理，并且没有更多可用空间。
SP_OUTOFMEMORY 没有足够的内存可用于后台处理。
SP_USERABORT 用户通过打印管理器终止了作业。

备注

此成员函数替换 ABORTDOC 打印机转义。

AbortDoc 应用于终止以下操作：

不使用 SetAbortProc 指定中止函数的打印操作。
尚未到达其第一个 NEWFRAME 或 NEXTBAND 转义调用的打印操作。

如果应用程序遇到打印错误或取消打印操作，则不得尝试使用 CDC 类的 EndDoc 或 AbortDoc 成员函数来终止操作。 GDI 在返回错误值之前自动终止操作。

如果应用程序显示一个对话框以允许用户取消打印操作，它必须在销毁对话框之前调用 AbortDoc。

如果使用打印管理器启动打印作业，则调用 AbortDoc 会擦除整个后台打印作业，打印机将不接收任何内容。如果打印管理器未用于启动打印作业，则数据可能在调用 AbortDoc 之前已发送到打印机。在这种情况下，打印机驱动程序将重置打印机（如果可能）并关闭打印作业。

示例

请参阅 CDC::StartDoc 的示例。

`CDC::AbortPath`

闭合并放弃设备上下文中的任何路径。

BOOL AbortPath();

返回值

如果该函数成功，则为非 0；否则为 0。

备注

如果设备上下文中有开放路径括号，则闭合路径括号并丢弃路径。如果设备上下文中存在封闭的路径，则丢弃该路径。

`CDC::AddMetaFileComment`

将注释从缓冲区复制到指定的增强格式图元文件中。

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

参数

nDataSize
指定注释缓冲区的长度，以字节为单位。

pCommentData
指向包含注释的缓冲区。

返回值

如果该函数成功，则为非 0；否则为 0。

注解

注释可能包括任何私人信息，例如，图片的来源及其创建日期。注释应以应用程序签名开头，后跟数据。注释不应包含特定于位置的数据。特定于位置的数据指定记录的位置，并且不应包含它，因为一个图元文件可能嵌入另一个图元文件中。此函数只能与增强型图元文件一起使用。

`CDC::AlphaBlend`

调用此成员函数，以显示具有透明或半透明像素的位图。

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

参数

xDest
指定目标矩形左上角的 x 坐标（以逻辑单元表示）。

yDest
指定目标矩形左上角的 y 坐标（以逻辑单元表示）。

nDestWidth
指定目标矩形的宽度（以逻辑单元表示）。

nDestHeight
指定目标矩形的高度（以逻辑单元表示）。

pSrcDC
指向源设备上下文的指针。

xSrc
指定源矩形左上角的 x 坐标（以逻辑单元表示）。

ySrc
指定源矩形左上角的 y 坐标（以逻辑单元表示）。

nSrcWidth
指定源矩形的宽度（以逻辑单元表示）。

nSrcHeight
指定源矩形的高度（以逻辑单元表示）。

blend
指定 BLENDFUNCTION 结构。

返回值

如果成功，则返回 TRUE；否则返回 FALSE。

备注

有关详细信息，请参阅 Windows SDK 中的 AlphaBlend。

`CDC::AngleArc`

绘制线段和弧线。

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

参数

x
指定圆心的逻辑 x 坐标。

y
指定圆心的逻辑 y 坐标。

nRadius
指定圆的半径（以逻辑单元表示）。该值必须是正数。

fStartAngle
指定相对于 x 轴的起始角度（以度为单位）。

fSweepAngle
指定相对于起始角度的扫描角度（以度为单位）。

返回值

如果成功，则不为 0；否则为 0。

注解

线段从当前位置绘制到弧线的起点。弧线沿具有给定半径和中心的圆的周长绘制。弧线的长度由给定的起始角度和扫描角度定义。

AngleArc 将当前位置移动到弧线的终点。此函数绘制的弧线可能看起来是椭圆的，具体取决于当前的转换和映射模式。在绘制弧线之前，此函数将绘制从当前位置到弧线起点的线段。通过围绕指定中心点构造一个具有指定半径的虚圆来绘制弧线。弧线的起点是通过从圆的 x 轴逆时针测量起始角的度数来确定的。通过从起点逆时针测量扫描角的度数，类似地定位终点。

如果扫描角度大于 360 度，弧线将多次扫描。此函数使用当前触笔绘制线条。该图形未填充。

`CDC::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);

参数

x1
指定边框左上角的 x 坐标（以逻辑单元表示）。

y1
指定边框左上角的 y 坐标（以逻辑单元表示）。

x2
指定边框右下角的 x 坐标（以逻辑单元表示）。

y2
指定边框右下角的 y 坐标（以逻辑单元表示）。

x3
指定定义弧线起点的点的 x 坐标（以逻辑单元表示）。此点不必完全位于弧线上。

y3
指定定义弧线起点的点的 y 坐标（以逻辑单元表示）。此点不必完全位于弧线上。

x4
指定定义弧线终点的点的 x 坐标（以逻辑单元表示）。此点不必完全位于弧线上。

y4
指定定义弧线终点的点的 y 坐标（以逻辑单元表示）。此点不必完全位于弧线上。

lpRect
指定边框（以逻辑单元表示）。可以为此参数传递 LPRECT 或 CRect 对象。

ptStart
指定定义弧线起点的点的 x 坐标和 y 坐标（以逻辑单元表示）。此点不必完全位于弧线上。可以为此参数传递 POINT 结构或 CPoint 对象。

ptEnd
指定定义弧线终点的点的 x 坐标和 y 坐标（以逻辑单元表示）。此点不必完全位于弧线上。可以为此参数传递 POINT 结构或 CPoint 对象。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

使用该函数绘制的弧线是由指定的边框定义的一段椭圆。

弧线的实际起点是从边框的中心通过指定起点绘制的射线与椭圆相交的点。弧线的实际终点是从边框的中心通过指定终点绘制的射线与椭圆相交的点。弧线是沿逆时针方向绘制的。由于弧线不是封闭图形，因此不会对其进行填充。矩形的宽度和高度都必须大于 2 个单元且小于 32,767 个单元。

示例

void CDCView::DrawArc(CDC *pDC)
{
   // Fill the client area with a thin circle. The circle's
   // interior is not filled. The circle's perimeter is
   // blue from 6 o'clock to 3 o'clock and red from 3
   // o'clock to 6 o'clock.

   // Get the client area.
   CRect rectClient;
   GetClientRect(rectClient);

   // Make a couple of pens.
   CPen penBlue;
   CPen penRed;
   CPen *pOldPen;

   penBlue.CreatePen(PS_SOLID | PS_COSMETIC, 1, RGB(0, 0, 255));
   penRed.CreatePen(PS_SOLID | PS_COSMETIC, 1, RGB(255, 0, 0));

   // Draw from 3 o'clock to 6 o'clock, counterclockwise,
   // in a blue pen.

   pOldPen = pDC->SelectObject(&penBlue);

   pDC->Arc(rectClient,
            CPoint(rectClient.right, rectClient.CenterPoint().y),
            CPoint(rectClient.CenterPoint().x, rectClient.right));

   // Draw from 6 o'clock to 3 o'clock, counterclockwise,
   // in a red pen.
   pDC->SelectObject(&penRed);

   // Keep the same parameters, but reverse start
   // and end points.
   pDC->Arc(rectClient,
            CPoint(rectClient.CenterPoint().x, rectClient.right),
            CPoint(rectClient.right, rectClient.CenterPoint().y));

   // Restore the previous pen.
   pDC->SelectObject(pOldPen);
}

`CDC::ArcTo`

绘制椭圆弧线。

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);

参数

x1
指定边框左上角的 x 坐标（以逻辑单元表示）。

y1
指定边框左上角的 y 坐标（以逻辑单元表示）。

x2
指定边框右下角的 x 坐标（以逻辑单元表示）。

y2
指定边框右下角的 y 坐标（以逻辑单元表示）。

x3
指定定义弧线起点的点的 x 坐标（以逻辑单元表示）。此点不必完全位于弧线上。

y3
指定定义弧线起点的点的 y 坐标（以逻辑单元表示）。此点不必完全位于弧线上。

x4
指定定义弧线终点的点的 x 坐标（以逻辑单元表示）。此点不必完全位于弧线上。

y4
指定定义弧线终点的点的 y 坐标（以逻辑单元表示）。此点不必完全位于弧线上。

lpRect
指定边框（以逻辑单元表示）。可以为此参数传递指向 RECT 数据结构或 CRect 对象的指针。

ptStart
指定定义弧线起点的点的 x 坐标和 y 坐标（以逻辑单元表示）。此点不必完全位于弧线上。可以为此参数传递 POINT 数据结构或 CPoint 对象。

ptEnd
指定定义弧线终点的点的 x 坐标和 y 坐标（以逻辑单元表示）。此点不必完全位于弧线上。可以为此参数传递 POINT 数据结构或 CPoint 对象。

返回值

如果该函数成功，则为非 0；否则为 0。

注解

此函数类似于 CDC::Arc，但当前位置已更新。点 (x1, y1) 和 (x2, y2) 指定边框。由给定边框形成的椭圆形定义了弧线的曲线。弧线从与从边框中心的径向线相交的点逆时针（默认弧线方向）延伸到 (*x3*, y3)。弧线在它与从边框中心到 (x4, y4) 的径向线相交处结束。如果起点和终点相同，则绘制一个完整的椭圆形。

绘制从当前位置到弧线起点的线条。如果未发生错误，则当前位置将设置为弧线的终点。使用当前笔绘制弧线；它未填充。

`CDC::Attach`

使用此成员函数将 hDC 附加到 CDC 对象。

BOOL Attach(HDC hDC);

参数

hDC
Windows 设备上下文。

返回值

如果该函数成功，则为非 0；否则为 0。

注解

hDC 存储在 m_hDC（输出设备上下文）和 m_hAttribDC（属性设备上下文）中。

`CDC::BeginPath`

在设备上下文中开放一个路径括号。

BOOL BeginPath();

返回值

如果该函数成功，则为非 0；否则为 0。

备注

开放路径括号后，应用程序可以开始调用 GDI 绘图函数来定义路径中的点。应用程序可以通过调用 EndPath 成员函数来闭合开放路径括号。当应用程序调用 BeginPath 时，将丢弃以前的任何路径。

有关定义路径中点的绘图函数的列表，请参阅 Windows SDK 中的 BeginPath。

示例

// This implementation uses GDI paths to draw the outline of
// some text in a TrueType font. The path is used to record the way
// the TrueType font would be drawn. Then, the function uses the data
// returned from CDC::GetPath() to draw the font--without filling it.
void CDCView::DrawPath(CDC *pDC)
{
   // Describe a 24-point truetype font of normal weight
   LOGFONT lf;
   memset(&lf, 0, sizeof(lf));
   lf.lfHeight = -MulDiv(24, pDC->GetDeviceCaps(LOGPIXELSY), 72);
   lf.lfWeight = FW_NORMAL;
   lf.lfOutPrecision = OUT_TT_ONLY_PRECIS;

   // create and select it
   CFont newFont;
   if (!newFont.CreateFontIndirect(&lf))
      return;
   CFont *pOldFont = pDC->SelectObject(&newFont);

   // use a path to record how the text was drawn
   pDC->BeginPath();
   pDC->TextOut(10, 10, _T("Outline this!"));
   pDC->EndPath();

   // Find out how many points are in the path. Note that
   // for long strings or complex fonts, this number might be
   // gigantic!
   int nNumPts = pDC->GetPath(NULL, NULL, 0);
   if (nNumPts == 0)
      return;

   // Allocate memory to hold points and stroke types from
   // the path.
   LPPOINT lpPoints = NULL;
   LPBYTE lpTypes = NULL;
   try
   {
      lpPoints = new POINT[nNumPts];
      lpTypes = new BYTE[nNumPts];
   }
   catch (CException *pe)
   {
      delete[] lpPoints;
      lpPoints = NULL;
      delete[] lpTypes;
      lpTypes = NULL;
      pe->Delete();
   }
   if (lpPoints == NULL || lpTypes == NULL)
      return;

   // Now that we have the memory, really get the path data.
   nNumPts = pDC->GetPath(lpPoints, lpTypes, nNumPts);

   // If it worked, draw the lines. Windows 98 doesn't support
   // the PolyDraw API, so we use our own member function to do
   // similar work. If you're targeting only later versions of
   // Windows, you can use the PolyDraw() API and avoid the
   // COutlineView::PolyDraw() member function.

   if (nNumPts != -1)
      pDC->PolyDraw(lpPoints, lpTypes, nNumPts);

   // Release the memory we used
   delete[] lpPoints;
   delete[] lpTypes;

   // Put back the old font
   pDC->SelectObject(pOldFont);

   return;
}

`CDC::BitBlt`

将位图从源设备上下文复制到当前设备上下文。

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

参数

x
指定目标矩形左上角的逻辑 x 坐标。

y
指定目标矩形左上角的逻辑 y 坐标。

nWidth
指定目标矩形和源位图的宽度（以逻辑单元表示）。

nHeight
指定目标矩形和源位图的高度（以逻辑单元表示）。

pSrcDC
指向 CDC 对象的指针，该对象标识要从中复制位图的设备上下文。如果 dwRop 指定不包含源的光栅操作，则它必须是 NULL。

xSrc
指定源位图左上角的逻辑 x 坐标。

ySrc
指定源位图左上角的逻辑 y 坐标。

dwRop
指定要执行的光栅操作。光栅操作代码定义 GDI 如何合并涉及当前画笔、可能的源位图和目标位图的输出操作中的颜色。有关 dwRop 的光栅操作代码列表及其说明，请参阅 Windows SDK 中的 BitBlt

有关光栅操作代码的完整列表，请参阅 Windows SDK 中的关于光栅操作代码。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

应用程序可以对齐字节边界上的窗口或工作区，以确保 BitBlt 操作发生在字节对齐的矩形上。（注册窗口类时，设置 CS_BYTEALIGNWINDOW 或 CS_BYTEALIGNCLIENT 标志。）

对字节对齐矩形的 BitBlt 操作比对非字节对齐矩形的 BitBlt 操作快得多。如果要为自己的设备上下文指定类样式（例如字节对齐），则必须注册窗口类，而不是依赖 Microsoft Foundation 类为你执行此操作。使用全局函数 AfxRegisterWndClass。

GDI 转换 nWidth 和 nHeight，使用目标设备上下文转换一次，使用源设备上下文转换一次。如果生成的范围不匹配，GDI 会根据需要使用 Windows StretchBlt 函数压缩或拉伸源位图。

如果目标位图、源位图和模式位图没有相同的颜色格式，BitBlt 函数将转换源位图和模式位图，以与目标位图匹配。在转换中将使用目标位图的前景色和背景色。

当 BitBlt 函数将单色位图转换为彩色位图时，它会将白色位 (1) 设置为背景色，将黑色位 (0) 设置为前景色。使用目标设备上下文的前景色和背景色。若要将彩色转换为单色，BitBlt 会将与背景色匹配的像素设置为白色，将所有其他像素设置为黑色。 BitBlt 使用颜色设备上下文的前景色和背景色从彩色转换为单色。

并非所有设备上下文都支持 BitBlt。若要检查给定设备上下文是否支持 BitBlt，请使用 GetDeviceCaps 成员函数并指定 RASTERCAPS 索引。

示例

请参阅 CDC::CreateCompatibleDC 的示例。

`CDC::CDC`

构造 CDC 对象。

CDC();

`CDC::Chord`

绘制弦形（由椭圆和线段的交点界定的封闭图形）。

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);

参数

x1
指定弦形的边框左上角的 x 坐标（以逻辑单元表示）。

y1
指定弦形的边框左上角的 y 坐标（以逻辑单元表示）。

x2
指定弦形的边框右下角的 x 坐标（以逻辑单元表示）。

y2
指定弦形的边框右下角的 y 坐标（以逻辑单元表示）。

x3
指定定义弦形起点的点的 x 坐标（以逻辑单元表示）。

y3
指定定义弦形起点的点的 y 坐标（以逻辑单元表示）。

x4
指定定义弦形终点的点的 x 坐标（以逻辑单元表示）。

y4
指定定义弦形终点的点的 y 坐标（以逻辑单元表示）。

lpRect
指定边框（以逻辑单元表示）。可以为此参数传递 LPRECT 或 CRect 对象。

ptStart
指定定义弦形起点的点的 x 坐标和 y 坐标（以逻辑单元表示）。此点不必完全位于弦形上。可以为此参数传递 POINT 结构或 CPoint 对象。

*ptEnd*
指定定义弦形终点的点的 x 坐标和 y 坐标（以逻辑单元表示）。此点不必完全位于弦形上。可以为此参数传递 POINT 结构或 CPoint 对象。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

(x1, y1) 和 (x2, y2) 参数分别指定矩形的左上角和右下角，该矩形形成作为弦形的一部分的椭圆形的边界。 (x3, y3) 和 (x4, y4) 参数指定与椭圆形相交的线条的端点。使用选定的触笔绘制弦形，并使用选定的画笔进行填充。

Chord 函数绘制的图形向上延伸到（但不包括）右侧和底部坐标。这意味着图形的高度是 y2 - y1，图形的宽度是 x2 - x1。

示例

void CDCView::DrawChord(CDC *pDC)
{
   // Fill the client area with a circle. The circle is
   // blue and filled with blue, but has a chord cut out
   // of it from 3 o'clock to 6 o'clock. That chord is
   // red and filled with a red diagonal hatch.

   // Get the client area.
   CRect rectClient;
   GetClientRect(rectClient);

   // Make a couple of pens and similar brushes.
   CPen penBlue, penRed;
   CBrush brushBlue, brushRed;
   CBrush *pOldBrush;
   CPen *pOldPen;

   brushBlue.CreateSolidBrush(RGB(0, 0, 255));
   brushRed.CreateHatchBrush(HS_FDIAGONAL, RGB(255, 0, 0));
   penBlue.CreatePen(PS_SOLID | PS_COSMETIC, 1, RGB(0, 0, 255));
   penRed.CreatePen(PS_SOLID | PS_COSMETIC, 1, RGB(255, 0, 0));

   // Draw from 3 o'clock to 6 o'clock, counterclockwise,
   // in a blue pen with a solid blue fill.
   pOldPen = pDC->SelectObject(&penBlue);
   pOldBrush = pDC->SelectObject(&brushBlue);

   pDC->Chord(rectClient,
              CPoint(rectClient.right, rectClient.CenterPoint().y),
              CPoint(rectClient.CenterPoint().x, rectClient.right));

   // Draw the remaining quarter chord from 6 o'clock
   // to 3 o'clock, counterclockwise, in a red pen
   // with the hatched brush.
   pDC->SelectObject(&penRed);
   pDC->SelectObject(&brushRed);

   // Keep the same parameters, but reverse start and
   // end points.
   pDC->Chord(rectClient,
              CPoint(rectClient.CenterPoint().x, rectClient.right),
              CPoint(rectClient.right, rectClient.CenterPoint().y));

   // Restore the previous pen.
   pDC->SelectObject(pOldPen);
}

`CDC::CloseFigure`

闭合路径中开放的图形。

BOOL CloseFigure();

返回值

如果该函数成功，则为非 0；否则为 0。

备注

该函数通过从当前位置到图形的第一个点（通常是最近一次调用 MoveTo 成员函数指定的点）绘制一条线来闭合图形，并使用线条联接样式连接这些线。如果使用 LineTo 成员函数而不是使用 CloseFigure 来闭合图形，则使用末端创建角而不是联接。仅当设备上下文中存在开放路径括号时才应调用 CloseFigure。

路径中的图处于开放状态，除非使用此函数显式将其闭合。（即使当前点和图形的起点相同，图形也可以处于开放状态。）CloseFigure 之后添加到路径的任何线条或曲线都会开始一个新图形。

`CDC::CreateCompatibleDC`

创建与 pDC 指定的设备兼容的内存设备上下文。

BOOL CreateCompatibleDC(CDC* pDC);

参数

pDC
一个指向设备上下文的指针。如果 pDC 是 NULL，该函数会创建一个与系统显示兼容的内存设备上下文。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

内存设备上下文是表示显示图面的内存块。它可用于在将图像复制到兼容设备的实际设备图面之前准备内存中的图像。

创建内存设备上下文时，GDI 会自动为其选择 1x1 单色库存位图。仅当已创建位图并将其选择到该上下文中时，才能将 GDI 输出函数与内存设备上下文一起使用。

此函数只能用于为支持光栅操作的设备创建兼容的设备上下文。有关设备上下文之间的位块传输的信息，请参阅 CDC::BitBlt 成员函数。若要确定设备上下文是否支持光栅操作，请参阅成员函数 CDC::GetDeviceCaps 中的 RC_BITBLT 光栅功能。

示例

// This handler loads a bitmap from system resources,
// centers it in the view, and uses BitBlt() to paint the bitmap
// bits.
void CDCView::DrawBitmap(CDC *pDC)
{
   // load IDB_BITMAP1 from our resources
   CBitmap bmp;
   if (bmp.LoadBitmap(IDB_BITMAP1))
   {
      // Get the size of the bitmap
      BITMAP bmpInfo;
      bmp.GetBitmap(&bmpInfo);

      // Create an in-memory DC compatible with the
      // display DC we're using to paint
      CDC dcMemory;
      dcMemory.CreateCompatibleDC(pDC);

      // Select the bitmap into the in-memory DC
      CBitmap *pOldBitmap = dcMemory.SelectObject(&bmp);

      // Find a centerpoint for the bitmap in the client area
      CRect rect;
      GetClientRect(&rect);
      int nX = rect.left + (rect.Width() - bmpInfo.bmWidth) / 2;
      int nY = rect.top + (rect.Height() - bmpInfo.bmHeight) / 2;

      // Copy the bits from the in-memory DC into the on-
      // screen DC to actually do the painting. Use the centerpoint
      // we computed for the target offset.
      pDC->BitBlt(nX, nY, bmpInfo.bmWidth, bmpInfo.bmHeight, &dcMemory,
                  0, 0, SRCCOPY);

      dcMemory.SelectObject(pOldBitmap);
   }
   else
   {
      TRACE0("ERROR: Where's IDB_BITMAP1?\n");
   }
}

`CDC::CreateDC`

为指定设备创建设备上下文。

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

参数

lpszDriverName
指向一个以 null 结尾的字符串，该字符串指定设备驱动程序的文件名（不带扩展名）（例如，“EPSON”）。还可以为此参数传递一个 CString 对象。

lpszDeviceName
指向一个以 null 结尾的字符串，该字符串指定要支持的特定设备的名称（例如，“EPSON FX-80”）。如果模块支持多个设备，则使用 lpszDeviceName 参数。还可以为此参数传递一个 CString 对象。

lpszOutput
指向一个以 null 结尾的字符串，该字符串指定物理输出介质（文件或输出端口）的文件名或设备名。还可以为此参数传递一个 CString 对象。

lpInitData
指向 DEVMODE 结构，其中包含设备驱动程序的设备特定初始化数据。 Windows DocumentProperties 函数检索为给定设备填充的此结构。如果设备驱动程序要使用用户通过控制面板指定的默认初始化（如果有），则 lpInitData 参数必须是 NULL。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

如果使用 DEVMODE 结构，则需要 PRINT.H 头文件。

设备名遵循以下约定：建议使用结束冒号 (:)，但可选。 Windows 会去除终止冒号，以便以冒号结尾的设备名映射到与没有冒号的相同名称相同的端口。驱动程序名称和端口名称不得包含前导或尾随空格。 GDI 输出函数不能与信息上下文一起使用。

`CDC::CreateIC`

为指定设备创建信息上下文。

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

参数

lpszDriverName
指向一个以 null 结尾的字符串，该字符串指定设备驱动程序的文件名（不带扩展名）（例如，“EPSON”）。可以为此参数传递一个 CString 对象。

lpszDeviceName
指向一个以 null 结尾的字符串，该字符串指定要支持的特定设备的名称（例如，“EPSON FX-80”）。如果模块支持多个设备，则使用 lpszDeviceName 参数。可以为此参数传递一个 CString 对象。

lpszOutput
指向一个以 null 结尾的字符串，该字符串指定物理输出介质（文件或端口）的文件名或设备名。可以为此参数传递一个 CString 对象。

lpInitData
指向设备驱动程序的设备特定初始化数据。如果设备驱动程序要使用用户通过控制面板指定的默认初始化（如果有），则 lpInitData 参数必须是 NULL。有关设备特定初始化的数据格式，请参阅 CreateDC。

返回值

如果成功，则不为 0；否则为 0。

备注

此信息上下文提供了一种无需创建设备上下文即可快速获取设备相关信息的方法。

`CDC::DeleteDC`

一般情况下，不要调用此函数；析构函数会为你执行此操作。

BOOL DeleteDC();

返回值

如果函数成功完成，则为非零；否则为 0。

备注

DeleteDC 成员函数删除与当前 CDC 对象中的 m_hDC 关联的 Windows 设备上下文。如果此 CDC 对象是给定设备的最后一个活动设备上下文，则会释放该设备使用的所有存储和系统资源。

如果已将对象选择到设备上下文中，则应用程序不应调用 DeleteDC。必须先从设备上下文中选择对象，然后才能将其删除。

应用程序不得删除通过调用 CWnd::GetDC 获得其句柄的设备上下文。相反，它必须调用 CWnd::ReleaseDC 来释放设备上下文。提供 CClientDC 和 CWindowDC 类来包装此功能。

DeleteDC 函数通常用于删除使用 CreateDC、CreateIC 或 CreateCompatibleDC 创建的设备上下文。

示例

请参阅 CPrintDialog::GetPrinterDC 的示例。

`CDC::DeleteTempMap`

由 CWinApp 空闲时间处理程序自动调用，DeleteTempMap 删除由 FromHandle 创建的任何临时 CDC 对象，但不会销毁与 CDC 对象临时关联的设备上下文句柄 (hDC)。

static void PASCAL DeleteTempMap();

`CDC::Detach`

调用此函数以从 CDC 对象中分离 m_hDC（输出设备上下文）并将 m_hDC 和 m_hAttribDC 都设置为 NULL。

HDC Detach();

返回值

Windows 设备上下文。

`CDC::DPtoHIMETRIC`

将 HIMETRIC 大小指定给 OLE 时使用此函数，将像素转换为 HIMETRIC。

void DPtoHIMETRIC(LPSIZE lpSize) const;

参数

lpSize
指向 SIZE 结构或 CSize 对象。

注解

如果设备上下文对象的映射模式是 MM_LOENGLISH、MM_HIENGLISH、MM_LOMETRIC 或 MM_HIMETRIC，则根据以物理英寸表示的像素数进行转换。如果映射模式是其他非约束模式之一（例如 MM_TEXT），则根据以逻辑英寸表示的像素数进行转换。

`CDC::DPtoLP`

将设备单元转换为逻辑单元。

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

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

参数

lpPoints
指向一组 POINT 结构或 CPoint 对象。

nCount
数组中的点数。

lpRect
指向 RECT 结构或 CRect 对象。此参数用于将一个矩形从设备点转换为逻辑点的简单情况。

lpSize
指向 SIZE 结构或 CSize 对象。

备注

该函数将每个点的坐标或大小的维度从设备坐标系映射到 GDI 的逻辑坐标系。转换取决于当前映射模式以及设备窗口和视区的原点和范围的设置。

`CDC::Draw3dRect`

调用此成员函数绘制一个三维矩形。

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

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

参数

lpRect
指定边框（以逻辑单元表示）。可以为此参数传递指向 RECT 结构或 CRect 对象的指针。

clrTopLeft
指定三维矩形的顶部和左侧的颜色。

clrBottomRight
指定三维矩形的底部和右侧的颜色。

x
指定三维矩形左上角的逻辑 x 坐标。

y
指定三维矩形左上角的逻辑 y 坐标。

cx
指定三维矩形的宽度。

cy
指定三维矩形的高度。

注解

矩形的顶部和左侧将以 clrTopLeft 指定的颜色绘制，底部和右侧以 clrBottomRight 指定的颜色绘制。

示例

void CDCView::Draw3dRect(CDC *pDC)
{
   // get the client area
   CRect rect;
   GetClientRect(rect);

   // shrink our rect 20 pixels on all sides
   rect.DeflateRect(20, 20);

   // draw a rectangle with red top and left sides, and
   // green right and bottom sides.
   pDC->Draw3dRect(rect, RGB(255, 0, 0), RGB(0, 255, 0));

   // This call to the four-integer override would draw
   // the same rectangle with a little less convenience:

   // pDC->Draw3dRect(rect.left, rect.top, rect.Width(), rect.Height(),
   //    RGB(255, 0, 0), RGB(0, 255, 0));
}

`CDC::DrawDragRect`

重复调用此成员函数，以重绘拖动矩形。

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

参数

lpRect
指向用于指定矩形逻辑坐标的 RECT 结构或 CRect 对象，在本例中，将重绘矩形的结束位置。

size
指定矩形从外边框左上角到内边框左上角的位移（即边框的粗细）。

lpRectLast
指向用于指定矩形位置逻辑坐标的 RECT 结构或 CRect 对象，在本例中，将重绘矩形的原始位置。

sizeLast
指定重绘的原始矩形从外边框左上角到内边框左上角的位移（即边框的粗细）。

pBrush
指向画笔对象的指针。设置为 NULL 以使用默认半色调画笔。

pBrushLast
指向使用的最后一个画笔对象的指针。设置为 NULL 以使用默认半色调画笔。

注解

在对鼠标位置进行采样时，在循环中调用它，以便提供视觉反馈。调用 DrawDragRect 时，将擦除上一个矩形，并绘制一个新矩形。例如，当用户在屏幕上拖动一个矩形时，DrawDragRect 将擦除原始矩形并在其新位置重新绘制一个新矩形。默认情况下，DrawDragRect 使用半色调画笔绘制矩形，以消除闪烁并创建平滑移动矩形的外观。

首次调用 DrawDragRect 时，参数 lpRectLast 应为 NULL。

`CDC::DrawEdge`

调用此成员函数，以绘制指定类型和样式的矩形的边缘。

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

参数

lpRect
指向包含矩形逻辑坐标的 RECT 结构的指针。

nEdge
指定要绘制的内部边缘和外部边缘的类型。此参数必须是一个内部边框标志和一个外边框标志的组合。有关参数类型的表，请参阅 Windows SDK 中的 DrawEdge。

nFlags
指定要绘制的边框类型的标志。有关参数值的表，请参阅 Windows SDK 中的 DrawEdge。对于对角线，BF_RECT 标志指定由矩形参数限定的向量的终点。

返回值

如果成功，则不为 0；否则为 0。

`CDC::DrawEscape`

访问不能通过图形设备接口 (GDI) 直接获得的视频显示的绘图功能。

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

参数

nEscape
指定要执行的转义函数。

nInputSize
指定 lpszInputData 参数指向的数据字节数。

lpszInputData
指向指定转义所需的输入结构。

返回值

指定函数的结果。如果成功，则大于零，但 QUERYESCSUPPORT 绘制转义除外，仅检查实现；如果未实施转义，则为 0；如果发生错误，则小于 0。

备注

当应用程序调用 DrawEscape 时，由 nInputSize 和 lpszInputData 标识的数据直接传递给指定的显示驱动程序。

`CDC::DrawFocusRect`

以用于指示矩形具有焦点的样式绘制一个矩形。

void DrawFocusRect(LPCRECT lpRect);

参数

lpRect
指向 RECT 结构或 CRect 对象，该结构或对象用于指定要绘制的矩形的逻辑坐标。

备注

由于这是一个布尔 XOR (^) 函数，因此使用同一矩形再次调用此函数会从显示中删除该矩形。无法滚动此函数绘制的矩形。若要滚动包含此函数绘制的矩形的区域，首先调用 DrawFocusRect 将矩形从显示中移除，然后滚动该区域，然后再次调用 DrawFocusRect 在新位置绘制矩形。

注意

DrawFocusRect 仅适用于 MM_TEXT 模式。在其他模式下，此函数不会正确绘制焦点矩形，但不会返回错误值。

`CDC::DrawFrameControl`

调用此成员函数，以绘制指定类型和样式的框架控件。

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

参数

lpRect
指向包含矩形逻辑坐标的 RECT 结构的指针。

nType
指定要绘制的框架控件的类型。有关此参数可能值的列表，请参阅 Windows SDK 中 DrawFrameControl 中的 uType 参数。

nState
指定框架控件的初始状态。可以是为 Windows SDK 中 DrawFrameControl 中的 uState 参数描述的一个或多个值。使用 nState 值 DFCS_ADJUSTRECT 调整边框，以排除下压按钮的周围边缘。

返回值

如果成功，则不为 0；否则为 0。

注解

在某些情况下，nState 取决于 nType 参数。以下列表显示了四个 nType 值与 nState 之间的关系：

DFC_BUTTON
- DFCS_BUTTON3STATE 三态按钮
- DFCS_BUTTONCHECK 复选框
- DFCS_BUTTONPUSH 下压按钮
- DFCS_BUTTONRADIO 单选按钮
- DFCS_BUTTONRADIOIMAGE 单选按钮的图像（非正方形需要图像）
- DFCS_BUTTONRADIOMASK 单选按钮的掩码（非正方形需要掩码）
DFC_CAPTION
- DFCS_CAPTIONCLOSE 关闭按钮
- DFCS_CAPTIONHELP 帮助按钮
- DFCS_CAPTIONMAX 最大化按钮
- DFCS_CAPTIONMIN 最小化按钮
- DFCS_CAPTIONRESTORE 还原按钮
DFC_MENU
- DFCS_MENUARROW 子菜单箭头
- DFCS_MENUBULLET 项目符号
- DFCS_MENUCHECK 选中标记
DFC_SCROLL
- DFCS_SCROLLCOMBOBOX 组合框滚动条
- DFCS_SCROLLDOWN 滚动条的向下箭头
- DFCS_SCROLLLEFT 滚动条的向左箭头
- DFCS_SCROLLRIGHT 滚动条的向右箭头
- DFCS_SCROLLSIZEGRIP 窗口右下角的大小调整手柄
- DFCS_SCROLLUP 滚动条的向上箭头

示例

此代码在窗口的右下角绘制大小调整手柄。它适用于对话框的 OnPaint 处理程序，该处理程序没有样式并且通常不包含可能为其提供大小调整手柄的其他控件（如状态栏）。

void CDCView::DrawFC(CDC *pDC)
{
   CRect rc;
   GetClientRect(&rc);

   rc.left = rc.right - ::GetSystemMetrics(SM_CXHSCROLL);
   rc.top = rc.bottom - ::GetSystemMetrics(SM_CYVSCROLL);

   pDC->DrawFrameControl(rc, DFC_SCROLL, DFCS_SCROLLSIZEGRIP);
}

`CDC::DrawIcon`

在当前 CDC 对象表示的设备上绘制图标。

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

BOOL DrawIcon(
    POINT point,
    HICON hIcon);

参数

x
指定图标左上角的逻辑 x 坐标。

y
指定图标左上角的逻辑 y 坐标。

hIcon
标识要绘制的图标的图柄。

point
指定图标左上角的逻辑 x 坐标和 y 坐标。可以为此参数传递 POINT 结构或 CPoint 对象。

返回值

如果函数成功完成，则为非零；否则为 0。

备注

该函数将图标的左上角放置在 x 和 y 指定的位置。该位置受设备上下文的当前映射模式的影响。

图标资源必须先前已使用函数 CWinApp::LoadIcon、CWinApp::LoadStandardIcon 或 CWinApp::LoadOEMIcon 加载。使用此函数前必须选择 MM_TEXT 映射模式。

示例

请参阅 CWnd::IsIconic 的示例。

`CDC::DrawState`

调用此成员函数，以显示图像并应用视觉效果来指示状态，例如已禁用或默认状态。

注意

对于除 DSS_NORMAL 之外的所有 nFlag 状态，图像在应用视觉效果之前转换为单色。

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);

参数

pt
指定图像的位置。

size
指定图像的大小。

hBitmap
位图的图柄。

nFlags
指定图像类型和状态的标志。有关可能的 nFlags 类型和状态，请参阅 Windows SDK 中的 DrawState。

hBrush
画笔的图柄。

pBitmap
一个指向 CBitmap 对象的指针。

pBrush
一个指向 CBrush 对象的指针。

hIcon
图标的图柄。

lpszText
指向文本的指针。

bPrefixText
可能包含加速器助记键的文本。 lData 参数指定字符串的地址，nTextLen 参数指定长度。如果 nTextLen 为 0，则假定字符串以 null 结尾。

nTextLen
lpszText 指向的文本字符串的长度。如果 nTextLen 为 0，则假定字符串以 null 结尾。

lpDrawProc
指向用于呈现图像的回调函数的指针。如果 nFlags 中的图像类型为 DST_COMPLEX，则此参数是必需的。如果图像类型为 DST_TEXT，则它是可选的并且可以是 NULL。对于所有其他图像类型，此参数将被忽略。有关回调函数的详细信息，请参阅 Windows SDK 中的 DrawStateProc 函数。

lData
指定有关图像的信息。此参数的含义取决于图像类型。

返回值

如果成功，则不为 0；否则为 0。

`CDC::DrawText`

调用此成员函数，以格式化给定矩形中的文本。若要指定更多格式设置选项，请使用 CDC::DrawTextEx。

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

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

参数

lpszString
指向要绘制的字符串。如果 nCount 为 -1，则字符串必须以 null 结尾。

nCount
指定字符串中的字符数。如果 nCount 为 -1，则假定 lpszString 是指向以 null 结尾的字符串的长指针，并且 DrawText 自动计算字符计数。

lpRect
指向 RECT 结构或 CRect 对象，其中包含要格式化文本的矩形（以逻辑坐标表示）。

str
包含要绘制的指定字符的 CString 对象。

nFormat
指定格式化文本的方法。它可以是为 Windows SDK 中 DrawText 中的 uFormat 参数描述的值的任意组合。（使用按位 OR 运算符组合）：

注意

某些 uFormat 标志组合可能会导致修改传递的字符串。将 DT_MODIFYSTRING 与 DT_END_ELLIPSIS 或 DT_PATH_ELLIPSIS 一起使用可能会导致字符串被修改，从而导致 CString 重写中的断言。值 DT_CALCRECT、DT_EXTERNALLEADING、DT_INTERNAL、DT_NOCLIP 和 DT_NOPREFIX 不能与 DT_TABSTOP 值一起使用。

返回值

如果函数成功，则为文本的高度。

备注

它可通过以下方式格式化文本：将制表符扩展到适当的空间、将文本与给定矩形的左、右或中心对齐，以及将文本分成适合给定矩形的行。格式类型由 nFormat 指定。

此成员函数使用设备上下文的选定字体、文本颜色和背景色来绘制文本。除非使用 DT_NOCLIP 格式，否则 DrawText 会剪切文本，以使文本不会出现在给定矩形之外。除非给出 DT_SINGLELINE 格式，否则假定所有格式都具有多行。

如果所选字体对于指定的矩形来说太大，DrawText 成员函数不会尝试替换较小的字体。

如果指定了 DT_CALCRECT 标志，则由 lpRect 指定的矩形将更新，以反映绘制文本所需的宽度和高度。

如果已设置 TA_UPDATECP 文本对齐标志（请参阅 CDC::SetTextAlign），DrawText 将显示从当前位置的文本，而不是从给定矩形的左侧开始的文本。设置 TA_UPDATECP 标志后，DrawText 不会进行文本换行（即 DT_WORDBREAK 标志将不起作用）。

文本颜色可以由 CDC::SetTextColor 设置。

`CDC::DrawTextEx`

格式化给定矩形中的文本。

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

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

参数

lpszString
指向要绘制的字符串。如果 nCount 为 -1，则字符串必须以 null 结尾。

nCount
指定字符串中的字符数。如果 nCount 为 -1，则假定 lpszString 是指向以 null 结尾的字符串的长指针，并且 DrawText 自动计算字符计数。

lpRect
指向 RECT 结构或 CRect 对象，其中包含要格式化文本的矩形（以逻辑坐标表示）。

str
包含要绘制的指定字符的 CString 对象。

nFormat
指定格式化文本的方法。它可以是为 Windows SDK 中 DrawText 中的 uFormat 参数描述的值的任意组合。（使用按位 OR 运算符组合）：

注意

lpDTParams
指向可指定更多格式设置选项的 DRAWTEXTPARAMS 结构的指针。此参数可以为 NULL。

注解

它可通过以下方式格式化文本：将制表符扩展到适当的空间、将文本与给定矩形的左、右或中心对齐，以及将文本分成适合给定矩形的行。格式类型由 nFormat 和 lpDTParams 指定。有关详细信息，请参阅 Windows SDK 中的 CDC::DrawText 和 DrawTextEx。

文本颜色可以由 CDC::SetTextColor 设置。

`CDC::Ellipse`

绘制椭圆形。

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

BOOL Ellipse(LPCRECT lpRect);

参数

x1
指定椭圆形边框左上角的逻辑 x 坐标。

y1
指定椭圆形边框左上角的逻辑 y 坐标。

x2
指定椭圆形边框右下角的逻辑 x 坐标。

y2
指定椭圆形边框右下角的逻辑 y 坐标。

lpRect
指定椭圆形的边框。还可以为此参数传递一个 CRect 对象。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

椭圆形的中心是由 x1、y1、x2 和 y2 或 lpRect 指定的边框的中心。椭圆形是用当前触笔绘制的，它的内部是用当前画笔填充的。

此函数绘制的图形向上延伸到（但不包括）右侧和底部坐标。这意味着图形的高度是 y2 - y1，图形的宽度是 x2 - x1。

如果边框的宽度或高度为 0，则不绘制椭圆形。

`CDC::EndDoc`

结束通过调用 StartDoc 成员函数启动的打印作业。

int EndDoc();

返回值

如果函数成功，则大于或等于 0，如果发生错误，则为负值。

注解

此成员函数替换 ENDDOC 打印机转义，应在成功完成打印作业后立即调用。

如果应用程序遇到打印错误或取消打印操作，它不得尝试使用 EndDoc 或 AbortDoc 来终止操作。 GDI 在返回错误值之前自动终止操作。

不应在图元文件内使用此函数。

示例

请参阅 CDC::StartDoc 的示例。

`CDC::EndPage`

通知设备应用程序已完成对页面的写入。

int EndPage();

返回值

如果函数成功，则大于或等于 0，如果发生错误，则为负值。

备注

此成员函数通常用于指示设备驱动程序进到新页面。

此成员函数替换 NEWFRAME 打印机转义。与 NEWFRAME 不同，此函数总是在打印页面后调用。

示例

请参阅 CDC::StartDoc 的示例。

`CDC::EndPath`

闭合路径括号，并选择括号定义的路径进入设备上下文。

BOOL EndPath();

返回值

如果该函数成功，则为非 0；否则为 0。

示例

请参阅 CDC::BeginPath 的示例。

`CDC::EnumObjects`

枚举设备上下文中可用的触笔和画笔。

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

参数

nObjectType
指定对象类型。它可以具有值 OBJ_BRUSH 或 OBJ_PEN。

lpfn
是应用程序提供的回调函数的过程实例地址。请参阅下面的“注解”部分。

lpData
指向应用程序提供的数据。数据与对象信息一起传递给回调函数。

返回值

指定回调函数返回的最后一个值。其含义是用户定义的。

备注

对于给定类型的每个对象，将使用该对象的信息调用所传递的回调函数。系统调用回调函数，直到没有更多对象或回调函数返回 0。

Microsoft Visual C++ 的新功能允许使用普通函数作为传递给 EnumObjects 的函数。传递给 EnumObjects 的地址是指向使用 EXPORT 和 Pascal 调用约定导出的函数的指针。在保护模式应用程序中，不必使用 Windows MakeProcInstance 函数创建此函数，也不必在使用 FreeProcInstance Windows 函数后释放该函数。

也不必在应用程序的模块定义文件的 EXPORTS 语句中导出函数名称。可以改为使用 EXPORT 函数修饰符，如

int CALLBACK EXPORT AFunction (LPSTR, LPSTR);

使编译器发出正确的导出记录，以便按名称（而不是别名）导出。这适用于大多数需求。对于某些特殊情况，例如按序号导出函数或为导出设置别名，仍然需要在模块定义文件中使用 EXPORTS 语句。

对于编译 Microsoft Foundation 程序，通常会使用 /GA 和 /GEs 编译器选项。 /Gw 编译器选项不与 Microsoft Foundation 类一起使用。（如果使用 Windows 函数 MakeProcInstance，则需要将返回的函数指针从 FARPROC 显式转换为此 API 所需的类型。）回调注册接口现在是类型安全的（必须传入一个函数指针，该指针指向特定回调的正确函数类型）。

另外，所有回调函数必须在返回到 Windows 之前捕获 Microsoft Foundation 异常，因为无法跨回调边界引发异常。有关异常的详细信息，请参阅异常一文。

示例

// print some info about a pen we're ready to enumerate
BOOL CALLBACK EnumObjectHandler(LPVOID lpLogObject, LPARAM /* lpData */)
{
   LOGPEN *pPen = (LOGPEN *)lpLogObject;

   switch (pPen->lopnStyle)
   {
   case PS_SOLID:
      TRACE0("PS_SOLID:      ");
      break;
   case PS_DASH:
      TRACE0("PS_DASH:       ");
      break;
   case PS_DOT:
      TRACE0("PS_DOT:        ");
      break;
   case PS_DASHDOT:
      TRACE0("PS_DASHDOT:    ");
      break;
   case PS_DASHDOTDOT:
      TRACE0("PS_DASHDOTDOT: ");
      break;
   case PS_NULL:
      TRACE0("PS_NULL:       ");
      break;
   case PS_INSIDEFRAME:
      TRACE0("PS_INSIDEFRAME:");
      break;
   default:
      TRACE0("unk style:");
   }

   TRACE2("Color: 0x%8.8X, Width: %d\n", pPen->lopnColor, pPen->lopnWidth);
   return TRUE;
}

// get the default printer and enumerate the pens it has
void CDCView::OnEnumPens()
{
   CPrintDialog dlg(FALSE);
   dlg.GetDefaults();
   HDC hdc = dlg.GetPrinterDC();

   if (hdc != NULL)
   {
      CDC dc;
      dc.Attach(hdc);
      VERIFY(dc.EnumObjects(OBJ_PEN, EnumObjectHandler, 0));
   }
}

`CDC::Escape`

对于 Win32 编程，此成员函数实际上已过时。

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

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

参数

nEscape
指定要执行的转义函数。

有关转义函数的完整列表，请参阅 Windows SDK 中的 Escape。

nCount
指定 lpszInData 指向的数据字节数。

lpszInData
指向此转义所需的输入数据结构。

lpOutData
指向要从此转义接收输出的结构。如果没有返回数据，则 lpOutData 参数为 NULL。

nInputSize
指定 lpszInputData 参数指向的数据字节数。

lpszInputData
指向指定转义所需的输入结构。

nOutputSize
指定 lpszOutputData 参数指向的数据字节数。

lpszOutputData
指向要从此转义接收输出的结构。如果没有返回数据，则此参数应为 NULL。

返回值

如果函数成功，则返回正值，但 QUERYESCSUPPORT 转义除外，只检查实现。如果未实施转义，则返回 0。如果发生错误，则返回负值。下面是常见的错误值：

SP_ERROR 常规错误。
SP_OUTOFDISK 当前没有足够的磁盘空间可用于后台处理，并且没有更多可用空间。
SP_OUTOFMEMORY 没有足够的内存可用于后台处理。
SP_USERABORT 用户通过打印管理器结束了作业。

备注

在原始打印机转义中，Win32 应用程序仅支持 QUERYESCSUPPORT。所有其他打印机转义都已过时，仅支持与 16 位应用程序兼容。

对于 Win32 编程，CDC 现在提供了六个成员函数来取代其相应的打印机转义：

CDC::AbortDoc
CDC::EndDoc
CDC::EndPage
CDC::SetAbortProc
CDC::StartDoc
CDC::StartPage

此外，CDC::GetDeviceCaps 支持取代其他打印机转义的 Win32 索引。有关详细信息，请参阅 Windows SDK 中的 GetDeviceCaps。

此成员函数允许应用程序访问不能通过 GDI 直接获得的特定设备的设施。

如果应用程序使用预定义的转义值，请使用第一个版本。如果应用程序定义了私有转义值，请使用第二个版本。有关第二个版本的详细信息，请参阅 Windows SDK 中的 ExtEscape。

`CDC::ExcludeClipRect`

创建一个由现有剪切区域减去指定矩形组成的新剪切区域。

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

int ExcludeClipRect(LPCRECT lpRect);

参数

x1
指定矩形左上角的逻辑 x 坐标。

y1
指定矩形左上角的逻辑 y 坐标。

x2
指定矩形右下角的逻辑 x 坐标。

y2
指定矩形右下角的逻辑 y 坐标。

lpRect
指定矩形。也可以是 CRect 对象。

返回值

指定新的剪切区域的类型。可以是以下任一值：

COMPLEXREGION 该区域有重叠的边框。
ERROR 未创建任何区域。
NULLREGION 该区域为空。
SIMPLEREGION 该区域没有重叠的边框。

注解

由 x2 - x1 的绝对值指定的矩形宽度不得超过 32,767 个单元。此限制也适用于矩形的高度。

`CDC::ExcludeUpdateRgn`

通过从与 CDC 对象关联的剪切区域中排除窗口中的更新区域来防止在窗口的无效区域内绘图。

int ExcludeUpdateRgn(CWnd* pWnd);

参数

pWnd
指向正在更新其窗口的窗口对象。

返回值

排除区域的类型。可以是以下任一值：

COMPLEXREGION 该区域有重叠的边框。
ERROR 未创建任何区域。
NULLREGION 该区域为空。
SIMPLEREGION 该区域没有重叠的边框。

`CDC::ExtFloodFill`

使用当前画笔填充显示图面的区域。

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

参数

x
指定填充开始的点的逻辑 x 坐标。

y
指定填充开始的点的逻辑 y 坐标。

crColor
指定要填充的边界或区域的颜色。 crColor 的解释取决于 nFillType 的值。

nFillType
指定要执行的洪水填充的类型。它必须是以下值之一：

FLOODFILLBORDER 该填充区域以 crColor 指定的颜色形成边界。此样式与 FloodFill 执行的填充相同。
FLOODFILLSURFACE 该填充区域由 crColor 指定的颜色定义。只要遇到颜色，就会沿所有方向继续向外填充。此样式可用于填充具有多色边界的区域。

返回值

如果函数成功，则为非零；否则，如果无法完成填充，如果给定点具有 crColor 指定的边界颜色（如果请求了 FLOODFILLBORDER），如果给定点不具有 crColor 指定的颜色（如果请求了 FLOODFILLSURFACE），或者如果该点在剪切区域之外，则为 0。

备注

此成员函数提供了比 FloodFill 更大的灵活性，因为可以在 nFillType 中指定填充类型。

如果 nFillType 设置为 FLOODFILLBORDER，则假定该区域完全由 crColor 指定的颜色形成边界。该函数从 x 和 y 指定的点开始并沿所有方向填充到颜色边界。

如果 nFillType 设置为 FLOODFILLSURFACE，则函数从 x 和 y 指定的点开始并沿所有方向继续填充包含 crColor 指定颜色的所有相邻区域。

只有内存设备上下文和支持光栅显示技术的设备才支持 ExtFloodFill。有关详细信息，请参阅 GetDeviceCaps 成员函数。

`CDC::ExtTextOut`

调用此成员函数，以使用当前选择的字体在矩形区域内写入字符串。

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);

参数

x
指定所指定字符串中第一个字符的字符单元格的逻辑 x 坐标。

y
指定所指定字符串中第一个字符的字符单元格顶部的逻辑 y 坐标。

nOptions
指定矩形类型。此参数可以是以下值之一、两者或都不是：

ETO_CLIPPED 指定将文本剪切到矩形。
ETO_OPAQUE 指定当前背景色填充矩形。（可以使用 SetBkColor 和 GetBkColor 成员函数设置和查询当前背景色。）

lpRect
指向确定矩形尺寸的 RECT 结构。此参数可以为 NULL。还可以为此参数传递一个 CRect 对象。

lpszString
指向要绘制的指定字符串。还可以为此参数传递一个 CString 对象。

nCount
指定字符串中的字符数。

lpDxWidths
指向一组值，这些值指示相邻字符单元格的原点之间的距离。例如，lpDxWidths[ i] 逻辑单元将分隔字符单元格 i 和字符单元格 i + 1 的原点。如果 lpDxWidths 是 NULL，则 ExtTextOut 使用字符之间的默认间距。

str
包含要绘制的指定字符的 CString 对象。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

矩形区域可以是不透明的（用当前背景色填充），也可以是剪切区域。

如果 nOptions 为 0 且 lpRect 为 NULL，则函数无需使用矩形区域即可将文本写入设备上下文。默认情况下，函数既不使用也不更新当前位置。如果应用程序在调用 ExtTextOut 时需要更新当前位置，则应用程序可以调用 CDC 成员函数 SetTextAlign，并将 nFlags 设置为 TA_UPDATECP。设置此标志后，Windows 会在后续调用 ExtTextOut 时忽略 x 和 y，并改用当前位置。当应用程序使用 TA_UPDATECP 更新当前位置时，ExtTextOut 将当前位置设置为上一行文本的末尾或 lpDxWidths 指向的数组的最后一个元素指定的位置，以较大者为准。

`CDC::FillPath`

闭合当前路径中所有开放的图形，并使用当前画笔和多边形填充模式填充路径的内部。

BOOL FillPath();

返回值

如果该函数成功，则为非 0；否则为 0。

注解

填充其内部后，该路径将从设备上下文中放弃。

`CDC::FillRect`

调用此成员函数，以使用指定的画笔填充给定的矩形。

void FillRect(
    LPCRECT lpRect,
    CBrush* pBrush);

参数

lpRect
指向 RECT 结构，其中包含要填充的矩形的逻辑坐标。还可以为此参数传递一个 CRect 对象。

pBrush
标识用于填充矩形的画笔。

注解

该函数填充整个矩形，包括左边框和上边框，但不填充右边框和下边框。

画笔需要使用 CBrush 成员函数 CreateHatchBrush、CreatePatternBrush 和 CreateSolidBrush 创建，或者由 GetStockObject Windows 函数检索。

填充指定矩形时，FillRect 不包括矩形的右侧和底部。无论当前的映射模式如何，GDI 都会填充矩形直到（但不包括）右列和底行。 FillRect 比较指定矩形的 top、bottom、left 和 right 成员的值。如果 bottom 小于或等于 top，或者如果 right 小于或等于 left，则不绘制矩形。

FillRect 类似于 CDC::FillSolidRect；但是，FillRect 采用画笔，因此可用于用纯色、抖动色、阴影画笔或图案填充矩形。 FillSolidRect 仅使用纯色（由 COLORREF 参数指示）。 FillRect 通常比 FillSolidRect 慢。

`CDC::FillRgn`

使用 pBrush 指定的画笔填充 pRgn 指定的区域。

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

参数

pRgn
指向要填充的区域的指针。给定区域的坐标以逻辑单元指定。

pBrush
标识要用于填充区域的画笔。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

画笔必须使用 CBrush 成员函数 CreateHatchBrush、CreatePatternBrush、CreateSolidBrush 创建或由 GetStockObject 检索。

示例

请参阅 CRgn::CreateRoundRectRgn 的示例。

`CDC::FillSolidRect`

调用此成员函数，以使用指定的纯色填充给定的矩形。

void FillSolidRect(
    LPCRECT lpRect,
    COLORREF clr);

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

参数

lpRect
指定边框（以逻辑单元表示）。可以为此参数传递指向 RECT 数据结构或 CRect 对象的指针。

clr 指定用于填充矩形的颜色。

x
指定矩形左上角的逻辑 x 坐标。

y
指定目标矩形左上角的逻辑 y 坐标。

cx
指定矩形的宽度。

cy
指定矩形的高度。

备注

FillSolidRect 与 CDC::FillRect 非常相似；但是，FillSolidRect 仅使用纯色（由 COLORREF 参数指示），而 FillRect 采用画笔，因此可用于用纯色、抖动色、阴影画笔或图案填充矩形。 FillSolidRect 通常比 FillRect 快。

注意

调用 FillSolidRect 时，之前使用 SetBkColor 设置的背景色设置为 clr 指示的颜色。

`CDC::FlattenPath`

将所选路径中的任何曲线转换为当前设备上下文，并将每个曲线转换为一系列线条。

BOOL FlattenPath();

返回值

如果该函数成功，则为非 0；否则为 0。

`CDC::FloodFill`

使用当前画笔填充显示图面的区域。

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

参数

x
指定填充开始的点的逻辑 x 坐标。

y
指定填充开始的点的逻辑 y 坐标。

crColor
指定边界的颜色。

返回值

如果函数成功，则为非零；否则返回 0，如果填充无法完成，给定点具有 crColor 指定的边界颜色，或者该点在剪切区域之外。

备注

假定区域由 crColor 指定为边界。 FloodFill 函数从 x 和 y 指定的点开始，并沿所有方向填充到颜色边界。

只有内存设备上下文和支持光栅显示技术的设备才支持 FloodFill 成员函数。有关 RC_BITBLT 功能的信息，请参阅 GetDeviceCaps 成员函数。

ExtFloodFill 函数提供了类似的功能，但灵活性更高。

`CDC::FrameRect`

在 lpRect 指定的矩形周围绘制边框。

void FrameRect(
    LPCRECT lpRect,
    CBrush* pBrush);

参数

lpRect
指向包含矩形左上角和右下角的逻辑坐标的 RECT 结构或 CRect 对象。还可以为此参数传递一个 CRect 对象。

pBrush
标识用于框定矩形的画笔。

备注

该函数使用给定的画笔绘制边框。边框的宽度和高度始终为 1 个逻辑单元。

如果矩形的 bottom 坐标小于或等于 top，或者如果 right 小于或等于 left，则不绘制矩形。

FrameRect 绘制的边框与 Rectangle 成员函数使用相同坐标绘制的边框位置相同（如果 Rectangle 使用 1 个逻辑单元宽的触笔）。矩形的内部未由 FrameRect 填充。

`CDC::FrameRgn`

使用 pBrush 指定的画笔在 pRgn 指定的区域周围绘制边框。

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

参数

pRgn
指向 CRgn 对象，该对象标识要包含在边框中的区域。给定区域的坐标以逻辑单元指定。

pBrush
指向 CBrush 对象，该对象标识要用于绘制边框的画笔。

nWidth
指定垂直画笔描边的边框宽度（以设备单元表示）。

nHeight
指定水平画笔描边的边框高度（以设备单元表示）。

返回值

如果该函数成功，则为非 0；否则为 0。

示例

请参阅 CRgn::CombineRgn 的示例。

`CDC::FromHandle`

在提供了设备上下文的句柄时返回指向 CDC 对象的指针。

static CDC* PASCAL FromHandle(HDC hDC);

参数

hDC
包含 Windows 设备上下文的句柄。

返回值

指针可能是临时的，不应在立即使用后存储。

注解

如果 CDC 对象未附加到该句柄，则会创建并附加一个临时 CDC 对象。

示例

请参阅 CPrintDialog::GetPrinterDC 的示例。

`CDC::GetArcDirection`

返回设备上下文的当前弧线方向。

int GetArcDirection() const;

返回值

指定当前弧线方向（如果成功）。下面是有效的返回值：

AD_COUNTERCLOCKWISE 逆时针绘制的弧线和矩形。
AD_CLOCKWISE Arcs 和顺时针绘制的矩形。

如果发生错误，则返回值为 0。

注解

弧线和矩形函数使用弧线方向。

`CDC::GetAspectRatioFilter`

检索当前纵横比筛选器的设置。

CSize GetAspectRatioFilter() const;

返回值

一个 CSize 对象，表示当前纵横比筛选器使用的纵横比。

备注

纵横比是设备的像素宽度和高度形成的比率。有关设备纵横比的信息用于字体的创建、选择和显示。 Windows 提供了一个特殊的筛选器（纵横比筛选器），用于从所有可用字体中选择为特定纵横比设计的字体。筛选器使用 SetMapperFlags 成员函数指定的纵横比。

`CDC::GetBkColor`

返回当前背景色。

COLORREF GetBkColor() const;

返回值

RGB 颜色值。

备注

如果背景模式为 OPAQUE，则系统使用背景色填充样式线中的空白、画笔中阴影线之间的空白以及字符单元格中的背景。在彩色和单色设备上下文之间转换位图时，系统还使用背景色。

CDC::GetBkMode

返回背景模式。

int GetBkMode() const;

返回值

当前后台模式，可以是 OPAQUE 或 TRANSPARENT。

备注

背景模式定义系统是否在绘制文本、阴影画笔或任何非实线的触笔样式之前删除绘图图面上的现有背景色。

`CDC::GetBoundsRect`

返回指定设备上下文的当前累积边框。

UINT GetBoundsRect(
    LPRECT lpRectBounds,
    UINT flags);

参数

lpRectBounds
指向将接收当前边框的缓冲区。矩形以逻辑坐标返回。

flags
指定是否在返回边框后将其清除。此参数应为 0 或设置为以下值：

DCB_RESET 强制在返回边框后将其清除。

返回值

如果函数成功，则指定边框的当前状态。它可以是以下值的组合：

DCB_ACCUMULATE 边框累积正在进行。
DCB_RESET 边框为空。
DCB_SET 边框不为空。
DCB_ENABLE 边界累积已开启。
DCB_DISABLE 边界累积已关闭。

`CDC::GetBrushOrg`

检索当前为设备上下文选择的画笔的原点（以设备单元表示）。

CPoint GetBrushOrg() const;

返回值

画笔的当前原点（以设备单元表示）作为 CPoint 对象。

备注

初始画笔原点位于工作区的 (0,0)。返回值相对于桌面窗口的原点指定此点（以设备单元表示）。

`CDC::GetCharacterPlacement`

检索有关字符串的各种信息。

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;

参数

lpString
指向要处理的字符串的指针。

nCount
指定字符串的长度。对于 ANSI 版本，它是一个 BYTE 计数，对于 Unicode 函数，它是一个 WORD 计数。有关详细信息，请参阅 GetCharacterPlacement。

nMaxExtent
指定处理字符串的最大范围（以逻辑单元表示）。如果已处理，将忽略超出此范围的字符。任何所需排序或字形数组的计算仅适用于包含的字符。仅当在 dwFlags 参数中指定了 GCP_MAXEXTENT 值时，才使用此参数。当函数处理输入字符串时，只有当总范围尚未超过最大值时，每个字符及其范围才会添加到输出、范围和其他数组中。达到限制后，处理将停止。

lpResults
指向接收函数结果的 GCP_Results 结构的指针。

dwFlags
指定如何将字符串处理成所需的数组。此参数可以是 GetCharacterPlacement 主题的 dwFlags 部分中列出的一个或多个值。

str
指向要处理的 CString 对象的指针。

返回值

如果函数成功，则返回值为字符串的宽度和高度（以逻辑单元表示）。

如果函数失败，则返回值为零。

备注

此成员函数模拟 GetCharacterPlacement 函数的功能，如 Windows SDK 中所述。

`CDC::GetCharABCWidths`

从当前 TrueType 字体中检索指定范围内的连续字符的宽度。

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

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

参数

nFirstChar
指定从当前字体返回字符宽度的字符范围中的第一个字符。

nLastChar
指定从当前字体返回字符宽度的字符范围中的最后一个字符。

lpabc
指向在函数返回时接收字符宽度的 ABC 结构数组。此数组的 ABC 结构数必须至少与 nFirstChar 和 nLastChar 参数指定范围内的字符一样多。

lpABCF
指向具有 ABCFLOAT 结构数组的应用程序提供的缓冲区，以在函数返回时接收字符宽度。此函数返回的宽度采用 IEEE 浮点格式。

返回值

如果该函数成功，则为非 0；否则为 0。

注解

宽度以逻辑单元返回。此功能仅适用于 TrueType 字体。

TrueType 光栅器在选择特定点大小后提供“ABC”字符间距。 “A”间距是在放置字形之前添加到当前位置的距离。 “B”间距是字形黑色部分的宽度。将“C”间距添加到当前位置，以考虑字形右侧的空白。总高级宽度由 A + B + C 提供。

当 GetCharABCWidths 成员函数检索字符的负“A”或“C”宽度时，该字符包括悬垂不足或悬垂过度。

若要将 ABC 宽度转换为字体设计单元，应用程序应创建一个字体，其高度（在 LOGFONT 结构的 lfHeight 成员中指定）等于存储在 NEWTEXTMETRIC 结构的 ntmSizeEM 成员中的值。（可以通过调用 EnumFontFamilies Windows 函数来检索 ntmSizeEM 成员的值。）

默认字符的 ABC 宽度用于当前所选字体范围之外的字符。

若要检索非 TrueType 字体中字符的宽度，应用程序应使用 GetCharWidth Windows 函数。

`CDC::GetCharABCWidthsI`

从当前 TrueType 字体检索指定范围内连续字形索引的宽度（以逻辑单元表示）。

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

参数

giFirst
指定当前字体的连续字形索引组中的第一个字形索引。仅在 pgi 参数为 NULL 时，才使用此参数。

cgi
指定字形索引的数量。

pgi
指向包含字形索引的数组的指针。如果值为 NULL，则使用 giFirst 参数。 cgi 参数指定此数组中字形索引的数量。

lpabc
指向接收字符宽度的 ABC 结构数组的指针。此数组必须包含至少与 cgi 参数指定的字形索引一样多的 ABC 结构。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

此成员函数模拟 GetCharABCWidthsI 函数的功能，如 Windows SDK 中所述。

`CDC::GetCharWidth`

使用输入设备上下文 m_hAttribDC 从当前字体检索连续字符组中各个字符的宽度。

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

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

参数

nFirstChar
指定当前字体中一组连续字符中的第一个字符。

nLastChar
指定当前字体中一组连续字符中的最后一个字符。

lpBuffer
指向一个缓冲区，该缓冲区将接收当前字体中一组连续字符的宽度值。

lpFloatBuffer
指向用于接收字符宽度的缓冲区。返回的宽度采用 32 位 IEEE 浮点格式。（宽度是沿着字符的基线测量的。）

返回值

如果该函数成功，则为非 0；否则为 0。

备注

例如，如果 nFirstChar 标识字母“a”而 nLastChar 标识字母“z”，则该函数将检索所有小写字符的宽度。

该函数将值存储在 lpBuffer 指向的缓冲区中。此缓冲区必须足够大，才能容纳所有宽度。也就是说，给定的示例中必须至少有 26 个条目。

如果这组连续字符中的某个字符在特定字体中不存在，则会为其分配默认字符的宽度值。

`CDC::GetCharWidthI`

从当前字体检索指定范围内连续字形索引的宽度（以逻辑坐标表示）。

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

参数

giFirst
指定当前字体的连续字形索引组中的第一个字形索引。仅在 pgi 参数为 NULL 时，才使用此参数。

cgi
指定字形索引的数量。

pgi
指向包含字形索引的数组的指针。如果值为 NULL，则使用 giFirst 参数。 cgi 参数指定此数组中字形索引的数量。

lpBuffer
指向接收宽度的缓冲区的指针。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

此成员函数模拟 GetCharWidthI 函数的功能，如 Windows SDK 中所述。

`CDC::GetClipBox`

检索围绕当前剪切边界的最紧密边框的尺寸。

virtual int GetClipBox(LPRECT lpRect) const;

参数

lpRect
指向要接收矩形尺寸的 RECT 结构或 CRect 对象。

返回值

剪切区域的类型。可以是以下任一值：

COMPLEXREGION 剪切区域有重叠的边框。
ERROR 设备上下文无效。
NULLREGION 剪切区域为空。
SIMPLEREGION 剪切区域没有重叠的边框。

备注

尺寸被复制到 lpRect 指向的缓冲区。

`CDC::GetColorAdjustment`

检索设备上下文的颜色调整值。

BOOL GetColorAdjustment(LPCOLORADJUSTMENT lpColorAdjust) const;

参数

lpColorAdjust
指向 COLORADJUSTMENT 数据结构以接收颜色调整值。

返回值

如果该函数成功，则为非 0；否则为 0。

`CDC::GetCurrentBitmap`

返回指向当前所选 CBitmap 对象的指针。

CBitmap* GetCurrentBitmap() const;

返回值

指向 CBitmap 对象的指针（如果成功）；否则为 NULL。

注解

此成员函数可能会返回临时对象。

`CDC::GetCurrentBrush`

返回指向当前所选 CBrush 对象的指针。

CBrush* GetCurrentBrush() const;

返回值

指向 CBrush 对象的指针（如果成功）；否则为 NULL。

备注

此成员函数可能会返回临时对象。

`CDC::GetCurrentFont`

返回指向当前所选 CFont 对象的指针。

CFont* GetCurrentFont() const;

返回值

指向 CFont 对象的指针（如果成功）；否则为 NULL。

注解

此成员函数可能会返回临时对象。

`CDC::GetCurrentPalette`

返回指向当前所选 CPalette 对象的指针。

CPalette* GetCurrentPalette() const;

返回值

指向 CPalette 对象的指针（如果成功）；否则为 NULL。

备注

此成员函数可能会返回临时对象。

`CDC::GetCurrentPen`

返回指向当前所选 CPen 对象的指针。

CPen* GetCurrentPen() const;

返回值

指向 CPen 对象的指针（如果成功）；否则为 NULL。

备注

此成员函数可能会返回临时对象。

`CDC::GetCurrentPosition`

检索当前位置（以逻辑坐标表示）。

CPoint GetCurrentPosition() const;

返回值

作为 CPoint 对象的当前位置。

备注

可以使用 MoveTo 成员函数设置当前位置。

`CDC::GetDCBrushColor`

检索当前画笔的颜色。

COLORREF GetDCBrushColor() const;

返回值

如果函数成功，返回值为当前画笔颜色的 COLORREF 值。

如果函数失败，则返回值为 CLR_INVALID。

注解

此成员函数模拟 GetDCBrushColor 函数的功能，如 Windows SDK 中所述。

`CDC::GetDCPenColor`

检索当前的钢笔颜色。

COLORREF GetDCPenColor() const;

返回值

如果函数成功，返回值为当前触笔颜色的 COLORREF 值。

如果函数失败，则返回值为 CLR_INVALID。

备注

此成员函数使用 Win32 函数 GetDCPenColor，如 Windows SDK 中所述。

`CDC::GetDeviceCaps`

检索有关显示设备的各种设备特定信息。

int GetDeviceCaps(int nIndex) const;

参数

nIndex
指定要返回的信息的类型。有关值列表，请参阅 Windows SDK 中的 GetDeviceCaps。

返回值

如果函数成功，则为所请求功能的值。

示例

请参阅 CPrintDialog::GetDefaults 的示例。

`CDC::GetFontData`

从可缩放字体文件检索字体指标信息。

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

参数

dwTable
指定要返回的指标表的名称。此参数可以是 Microsoft Corporation 发布的 TrueType 字体文件规范中记录的指标表之一。如果此参数为 0，则从字体文件的开头开始检索信息。

dwOffset
指定要开始检索信息的表开头的偏移量。如果此参数为 0，则从 dwTable 参数指定表的开头开始检索信息。如果此值大于或等于表的大小，则 GetFontData 返回 0。

lpData
指向将接收字体信息的缓冲区。如果此值为 NULL，则函数返回 dwTable 参数中指定的字体数据所需的缓冲区大小。

cbData
指定要检索的信息的长度（以字节为单位）。如果此参数为 0，则 GetFontData 返回 dwTable 参数中指定的数据大小。

返回值

如果函数成功，则指定 lpData 指向的缓冲区中返回的字节数；否则为 -1。

备注

通过指定字体文件的偏移量和要返回的信息的长度来识别要检索的信息。

应用程序有时可以使用 GetFontData 成员函数通过文档保存 TrueType 字体。为此，应用程序确定是否可以嵌入字体，然后检索整个字体文件，将 dwTable、dwOffset 和 cbData 参数指定为 0。

应用程序可以通过检查 OUTLINETEXTMETRIC 结构的 otmfsType 成员来确定是否可以嵌入字体。如果设置了 otmfsType 的第 1 位，则字体不允许嵌入。如果第 1 位被清除，则可以嵌入字体。如果设置了第 2 位，则嵌入是只读的。

如果应用程序尝试使用此函数检索非 TrueType 字体的信息，则 GetFontData 成员函数将返回 -1。

`CDC::GetFontLanguageInfo`

返回有关指定显示上下文的当前选定字体的信息。

DWORD GetFontLanguageInfo() const;

返回值

返回值标识当前所选字体的特征。有关可能值的完整列表，请参阅 GetFontLanguageInfo。

注解

此成员函数模拟 GetFontLanguageInfo 函数的功能，如 Windows SDK 中所述。

`CDC::GetGlyphOutline`

检索当前字体中轮廓字符的轮廓曲线或位图。

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

参数

nChar
指定要为其返回信息的字符。

nFormat
指定函数返回信息的格式。可以是以下值之一或 0：

值	含义
`GGO_BITMAP`	返回字形位图。函数返回时，`lpBuffer` 指向的缓冲区包含一个每像素 1 位的位图，其行从双字边界开始。
`GGO_NATIVE`	使用设备单元以光栅器的本机格式返回曲线数据点。指定此值时，将忽略 `lpmat2` 中指定的任何转换。

当 nFormat 的值为 0 时，函数填充 GLYPHMETRICS 结构，但不返回字形轮廓数据。

lpgm
指向描述字形在字符单元格中的位置的 GLYPHMETRICS 结构。

cbBuffer
指定函数将有关轮廓字符的信息复制到其中的缓冲区的大小。如果此值为 0，并且 nFormat 参数是 GGO_BITMAP 或 GGO_NATIVE 值，则函数返回所需的缓冲区大小。

lpBuffer
指向一个缓冲区，函数将有关轮廓字符的信息复制到该缓冲区中。如果 nFormat 指定 GGO_NATIVE 值，则以 TTPOLYGONHEADER 和 TTPOLYCURVE 结构的形式复制信息。如果此值为 NULL，并且 nFormat 为 GGO_BITMAP 或 GGO_NATIVE 值，则函数返回所需的缓冲区大小。

lpmat2
指向包含字符转换矩阵的 MAT2 结构。此参数不能为 NULL，即使为 nFormat 指定了 GGO_NATIVE 值也是如此。

返回值

如果 cbBuffer 为 0 或 lpBuffer 为 NULL，则为检索信息所需的缓冲区大小（以字节为单位）。否则，如果函数成功，则为正值，如果存在错误，则为 -1。

备注

应用程序可以通过在 lpmat2 指向的结构中指定一个 2×2 转换矩阵来旋转以位图格式检索的字符。

字形轮廓作为一系列外形返回。每个外形由一个 TTPOLYGONHEADER 结构定义，后跟描述它所需的多个 TTPOLYCURVE 结构。所有点都作为 POINTFX 结构返回，表示绝对位置，而不是相对移动。 TTPOLYGONHEADER 结构的 pfxStart 成员给出的起点是外形的轮廓开始的点。后面的 TTPOLYCURVE 结构可以是折线记录或曲线记录。折线记录是一系列点；在点之间绘制的线条描述字符的轮廓。曲线记录表示 TrueType 使用的二次曲线（即二次 b 曲线）。

`CDC::GetGraphicsMode`

检索指定设备上下文的当前图形模式。

int GetGraphicsMode() const;

返回值

成功时返回当前图形模式。有关此方法可以返回的值的列表，请参阅 GetGraphicsMode。

失败时返回 0。

若要获得扩展的错误信息，请调用 GetLastError。

备注

此方法包装 Windows GDI 函数 GetGraphicsMode。

`CDC::GetHalftoneBrush`

调用此成员函数，以检索半色调画笔。

static CBrush* PASCAL GetHalftoneBrush();

返回值

如果成功，则为指向 CBrush 对象的指针；否则为 NULL。

备注

半色调画笔显示交替出现的前景色和背景色的像素，以创建抖动图案。下图显示由半色调画笔创建的抖动图案示例：

Diagram that shows how a dithered pen stroke is composed.

`CDC::GetKerningPairs`

检索当前在指定设备上下文中选择的字体的字符间距调整对。

int GetKerningPairs(
    int nPairs,
    LPKERNINGPAIR lpkrnpair) const;

参数

nPairs
指定 lpkrnpair 指向的 KERNINGPAIR 结构的数量。该函数不会复制超出 nPairs 指定的字距的字距调整对。

lpkrnpair
指向在函数返回时接收字距调整对的 KERNINGPAIR 结构数组。此数组必须包含至少与 nPairs 指定的一样多的结构。如果此参数为 NULL，则函数返回字体的字距调整对的总数。

返回值

如果函数成功，则指定检索到的字距调整对的数量或字体中的字距调整对的总数。如果函数失败或没有字体的字距调整对，则返回 0。

`CDC::GetLayout`

调用此成员函数，以确定设备上下文（例如打印机或图元文件）的文本和图形的布局。

DWORD GetLayout() const;

返回值

如果成功，则为当前设备上下文的布局标志。否则为 GDI_ERROR。若要获得更多的错误信息，请调用 GetLastError。有关布局标志的列表，请参阅 CDC::SetLayout。

注解

默认布局是从左到右。

`CDC::GetMapMode`

检索当前映射模式。

int GetMapMode() const;

返回值

映射模式。

备注

有关映射模式的说明，请参阅 SetMapMode 成员函数。

注意

如果调用 SetLayout 将 DC 更改为从右到左的布局，SetLayout 会自动将映射模式更改为 MM_ISOTROPIC。因此，对 GetMapMode 的任何后续调用都将返回 MM_ISOTROPIC。

`CDC::GetMiterLimit`

返回设备上下文的斜接限制。

float GetMiterLimit() const;

返回值

如果该函数成功，则为非 0；否则为 0。

备注

绘制具有斜角连接的几何线时使用斜接限制。

`CDC::GetNearestColor`

返回与指定逻辑颜色最匹配的纯色。

COLORREF GetNearestColor(COLORREF crColor) const;

参数

crColor
指定要匹配的颜色。

返回值

一个 RGB（红、绿、蓝）颜色值，用于定义最接近设备可以表示的 crColor 值的纯色。

备注

给定设备必须能够表示此颜色。

`CDC::GetOutlineTextMetrics`

检索 TrueType 字体的指标信息。

UINT GetOutlineTextMetrics(
    UINT cbData,
    LPOUTLINETEXTMETRIC lpotm) const;

参数

lpotm
指向一组 OUTLINETEXTMETRIC 结构。如果此参数为 NULL，则函数返回检索到的指标数据所需的缓冲区大小。

cbData
指定信息返回到的缓冲区的大小（以字节为单位）。

lpotm
指向 OUTLINETEXTMETRIC 结构。如果此参数为 NULL，则函数返回检索到的指标信息所需的缓冲区大小。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

OUTLINETEXTMETRIC 结构包含随 TrueType 格式提供的大部分字体指标信息，包括 TEXTMETRIC 结构。 OUTLINETEXTMETRIC 结构的最后四个成员是指向字符串的指针。除了其他成员所需的空间外，应用程序还应为这些字符串分配空间。由于字符串大小没有系统强加的限制，因此分配内存的最简单方法是通过在第一次调用 GetOutlineTextMetrics 函数时为 lpotm 指定 NULL 来检索所需的大小。

`CDC::GetOutputCharWidth`

使用输出设备上下文 m_hDC，并从当前字体检索一组连续字符中各个字符的宽度。

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

参数

nFirstChar
指定当前字体中一组连续字符中的第一个字符。

nLastChar
指定当前字体中一组连续字符中的最后一个字符。

lpBuffer
指向一个缓冲区，该缓冲区将接收当前字体中一组连续字符的宽度值。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

例如，如果 nFirstChar 标识字母“a”而 nLastChar 标识字母“z”，则该函数将检索所有小写字符的宽度。

该函数将值存储在 lpBuffer 指向的缓冲区中。此缓冲区必须足够大，才能容纳所有宽度；也就是说，在给定的示例中，必须至少有 26 个条目。

如果这组连续字符中的某个字符在特定字体中不存在，则会为其分配默认字符的宽度值。

`CDC::GetOutputTabbedTextExtent`

调用此成员函数，以使用输出设备上下文 m_hDC 计算字符串的宽度和高度。

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

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

参数

lpszString
指向要测量的字符串。还可以为此参数传递一个 CString 对象。

nCount
指定 lpszString 指向的字符串的长度。

nTabPositions
指定 lpnTabStopPositions 指向的数组中的制表位位置数。

lpnTabStopPositions
指向包含逻辑单元制表位位置的整数数组。制表位必须按升序排列；最小的 x 值应该是数组中的第一项。不允许使用退格制表符。

str
包含要测量的指定字符的 CString 对象。

返回值

CSize 对象中字符串的尺寸（以逻辑单元表示）。

备注

如果字符串包含一个或多个制表符，则字符串的宽度基于 lpnTabStopPositions 指定的制表位。该函数使用当前选定的字体来计算字符串的尺寸。

当前剪切区域不会偏移 GetOutputTabbedTextExtent 函数返回的宽度和高度。

由于某些设备不会将字符放置在常规单元格数组中（即，它们对字符进行字距调整），因此字符串中字符范围的总和可能不等于字符串的范围。

如果 nTabPositions 为 0 且 lpnTabStopPositions 为 NULL，则制表符扩展为 8 个平均字符宽度。如果 nTabPositions 为 1，则制表位将按由 lpnTabStopPositions 指向的数组中的第一个值指定的距离分隔。如果 lpnTabStopPositions 指向多个值，则为数组中的每个值设置一个制表位，最多为 nTabPositions 指定的数字。

`CDC::GetOutputTextExtent`

调用此成员函数，以使用输出设备上下文 m_hDC，并使用当前字体计算一行文本的宽度和高度。

CSize GetOutputTextExtent(
    LPCTSTR lpszString,
    int nCount) const;

CSize GetOutputTextExtent(const CString& str) const;

参数

lpszString
指向一串字符。还可以为此参数传递一个 CString 对象。

nCount
指定 lpszString 指向的字符串的长度。

str
包含要测量的指定字符的 CString 对象。

返回值

CSize 对象中返回的字符串的尺寸（以逻辑单元表示）。

备注

当前剪切区域不会影响 GetOutputTextExtent 返回的宽度和高度。

由于某些设备不会将字符放置在常规单元格数组中（即，它们执行字距调整），因此字符串中字符范围的总和可能不等于字符串的范围。

`CDC::GetOutputTextMetrics`

使用输出设备上下文 m_hDC 检索当前字体的指标。

BOOL GetOutputTextMetrics(LPTEXTMETRIC lpMetrics) const;

参数

lpMetrics
指向接收指标的 TEXTMETRIC 结构。

返回值

如果该函数成功，则为非 0；否则为 0。

`CDC::GetPath`

检索定义线端点的坐标，以及在设备上下文中选择的路径中找到的曲线的控制点。

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

参数

lpPoints
指向放置线端点和曲线控制点的 POINT 数据结构或 CPoint 对象的数组。

lpTypes
指向放置顶点类型的字节数组。值为以下之一：

PT_MOVETO 指定 lpPoints 中的对应点开始一个不相交的图形。
PT_LINETO 指定前一个点和 lpPoints 中的对应点是一条线的端点。
PT_BEZIERTO 指定 lpPoints 中的对应点是贝塞尔曲线的控制点或终点。

PT_BEZIERTO 类型总是以三个一组出现。紧邻它们之前的路径中的点定义贝塞尔曲线的起点。前两个 PT_BEZIERTO 点是控制点，第三个 PT_BEZIERTO 点是终点（如果硬编码）。

PT_LINETO 或 PT_BEZIERTO 类型可以与以下标志组合（通过使用按位运算符 OR）来指示对应点是图形中的最后一个点并且应该闭合图形：

PT_CLOSEFIGURE 指定绘制相应的线条或曲线后图形自动闭合。通过从线条或曲线端点到对应于最后一个 PT_MOVETO 的点绘制一条线来闭合图形。

nCount
指定可以放置在 lpPoints 数组中的 POINT 数据结构的总数。此值必须与可放置在 lpTypes 数组中的字节数相同。

返回值

如果 nCount 参数为非零，则返回值为枚举的点数。如果 nCount 为 0，则返回值为路径中点的总数（并且 GetPath 不向缓冲区写入任何内容）。如果 nCount 为非零值且小于路径中的点数，则返回值为 -1。

备注

设备上下文必须包含封闭的路径。路径的点以逻辑坐标返回。点以设备坐标的形式存储在路径中，因此 GetPath 通过使用当前转换的反转将点从设备坐标更改为逻辑坐标。 FlattenPath 成员函数可以在 GetPath 之前调用，将路径中的所有曲线转换为线段。

示例

请参阅 CDC::BeginPath 的示例。

`CDC::GetPixel`

检索由 x 和 *y* 指定的点处像素的 RGB 颜色值。

COLORREF GetPixel(
    int x,
    int y) const;

COLORREF GetPixel(POINT point) const;

参数

x
指定要检查的点的逻辑 x 坐标。

y
指定要检查的点的逻辑 y 坐标。

point
指定要检查的点的逻辑 x 坐标和 y 坐标。

返回值

对于函数的任一版本，返回值为给定点的颜色的 RGB 颜色值。如果坐标未指定剪切区域中的点，则返回值为 -1。

备注

该点必须位于剪切区域中。如果该点不在剪切区域中，则函数不起作用，并返回 -1。

不是所有的设备都支持 GetPixel 函数。有关详细信息，请参阅 GetDeviceCaps 成员函数下的 RC_BITBLT 光栅功能。

GetPixel 成员函数有两种形式。第一种形式采用两个坐标值；第二种形式采用 POINT 结构或 CPoint 对象。

`CDC::GetPolyFillMode`

检索当前多边形填充模式。

int GetPolyFillMode() const;

返回值

如果函数成功，返回值为当前的多边形填充模式 ALTERNATE 或 WINDING。

备注

有关多边形填充模式的说明，请参阅 SetPolyFillMode 成员函数。

`CDC::GetROP2`

检索当前绘图模式。

int GetROP2() const;

返回值

绘图模式。有关绘图模式值的列表，请参阅 SetROP2 成员函数。

注解

绘图模式指定触笔的颜色和填充对象的内部如何与显示图面上已有的颜色组合。

`CDC::GetSafeHdc`

调用此成员函数，以获取输出设备上下文 m_hDC。

HDC GetSafeHdc() const;

返回值

设备上下文句柄。

注解

此成员函数也适用于 null 指针。

`CDC::GetStretchBltMode`

检索当前位图拉伸模式。

int GetStretchBltMode() const;

返回值

如果函数成功，则返回值指定当前位图拉伸模式 — STRETCH_ANDSCANS、STRETCH_DELETESCANS 或 STRETCH_ORSCANS。

注解

位图拉伸模式定义如何从由 StretchBlt 成员函数拉伸或压缩的位图中删除信息。

STRETCH_ANDSCANS 和 STRETCH_ORSCANS 模式通常用于保留单色位图中的前景像素。 STRETCH_DELETESCANS 模式通常用于保留彩色位图中的颜色。

`CDC::GetTabbedTextExtent`

调用此成员函数，以使用属性设备上下文 m_hAttribDC 计算字符串的宽度和高度。

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

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

参数

lpszString
指向字符串。还可以为此参数传递一个 CString 对象。

nCount
指定 lpszString 指向的字符串的长度。

nTabPositions
指定 lpnTabStopPositions 指向的数组中的制表位位置数。

lpnTabStopPositions
指向包含逻辑单元制表位位置的整数数组。制表位必须按升序排列；最小的 x 值应该是数组中的第一项。不允许使用退格制表符。

str
包含要绘制的指定字符的 CString 对象。

返回值

CSize 对象中字符串的尺寸（以逻辑单元表示）。

备注

如果字符串包含一个或多个制表符，则字符串的宽度基于 lpnTabStopPositions 指定的制表位。该函数使用当前选定的字体来计算字符串的尺寸。

当前剪切区域不会偏移 GetTabbedTextExtent 函数返回的宽度和高度。

由于某些设备不会将字符放置在常规单元格数组中（即，它们对字符进行字距调整），因此字符串中字符范围的总和可能不等于字符串的范围。

如果 nTabPositions 为 0 且 lpnTabStopPositions 为 NULL，则制表符将扩展为平均字符宽度的八倍。如果 nTabPositions 为 1，则制表位将按由 lpnTabStopPositions 指向的数组中的第一个值指定的距离分隔。如果 lpnTabStopPositions 指向多个值，则为数组中的每个值设置一个制表位，最多为 nTabPositions 指定的数字。

`CDC::GetTextAlign`

检索设备上下文的文本对齐标志的状态。

UINT GetTextAlign() const;

返回值

文本对齐标志的状态。返回值为以下一个或多个值：

TA_BASELINE 指定边框内 x 轴和所选字体基线的对齐方式。
TA_BOTTOM 指定 x 轴与边框底部的对齐方式。
TA_CENTER 指定 y 轴与边框中心的对齐方式。
TA_LEFT 指定 y 轴与边框左侧的对齐方式。
TA_NOUPDATECP 指定不更新当前位置。
TA_RIGHT 指定 y 轴与边框右侧的对齐方式。
TA_TOP 指定 x 轴与边框顶部的对齐方式。
TA_UPDATECP 指定更新当前位置。

注解

文本对齐标志确定 TextOut 和 ExtTextOut 成员函数如何相对于字符串的起始点对齐文本字符串。文本对齐标志不一定是单个位标志，可能等于 0。若要测试是否设置了标志，应用程序应遵循以下步骤：

将按位 OR (|) 运算符应用于标志及其相关标志，分组如下：
- TA_LEFT、TA_CENTER 和 TA_RIGHT
- TA_BASELINE、TA_BOTTOM 和 TA_TOP
- TA_NOUPDATECP 和 TA_UPDATECP
将 C++ 按位 AND (&) 运算符应用于 GetTextAlign 的结果和返回值。
测试此结果和标志的相等性。

`CDC::GetTextCharacterExtra`

检索字符间间距的当前设置。

int GetTextCharacterExtra() const;

返回值

字符间的间距量。

备注

当 GDI 将一行文本写入设备上下文时，它会将此间距添加到每个字符（包括中断字符）。

字符间的间距量的默认值为 0。

`CDC::GetTextColor`

检索当前的文本颜色。

COLORREF GetTextColor() const;

返回值

当前文本颜色（RGB 颜色值）。

备注

文本颜色是使用 GDI 文本输出成员函数 TextOut、ExtTextOut 和 TabbedTextOut 绘制的字符的前景色。

`CDC::GetTextExtent`

调用此成员函数，以使用当前字体计算一行文本的宽度和高度以确定尺寸。

CSize GetTextExtent(
    LPCTSTR lpszString,
    int nCount) const;

CSize GetTextExtent(const CString& str) const;

参数

lpszString
指向一串字符。还可以为此参数传递一个 CString 对象。

nCount
指定字符串中的字符数。

str
包含指定字符的 CString 对象。

返回值

CSize 对象中字符串的尺寸（以逻辑单元表示）。

注解

从属性设备上下文 m_hAttribDC 检索信息。

默认情况下，GetTextExtent 假定它检索尺寸的文本沿水平线设置（即，转义为 0）。如果创建指定非 0 转义的字体，则必须显式转换文本的角度以获取字符串的尺寸。

当前剪切区域不会影响 GetTextExtent 返回的宽度和高度。

由于某些设备不会将字符放置在常规单元格数组中（即，它们执行字距调整），因此字符串中字符范围的总和可能不等于字符串的范围。

`CDC::GetTextExtentExPointI`

检索指定字符串中适合指定空间的字符数，并用其中每个字符的文本范围填充数组。

BOOL GetTextExtentExPointI(
    LPWORD pgiIn,
    int cgi,
    int nMaxExtent,
    LPINT lpnFit,
    LPINT alpDx,
    LPSIZE lpSize) const;

参数

pgiIn
指向要检索其范围的字形索引数组的指针。

cgi
指定 pgiIn 指向的数组中字形的数量。

nMaxExtent
指定格式化字符串的最大允许宽度（以逻辑单元表示）。

lpnFit
一个指向整数的指针，该整数接收将适合 nMaxExtent 指定的空间的最大字符数的计数。当 lpnFit 为 NULL 时，会忽略 nMaxExtent。

alpDx
指向接收部分字形范围的整数数组的指针。数组中的每个元素都给出了字形索引数组的开头和适合 nMaxExtent 指定空间的字形之一之间的距离（以逻辑单元表示）。尽管此数组的元素数应至少与 cgi 指定的字形索引一样多，但该函数仅使用 lpnFit 指定的字形索引的范围填充数组。如果 lpnDx 是 NULL，则该函数不计算部分字符串宽度。

lpSize
指向 SIZE 结构的指针，该结构接收字形索引数组的维度（以逻辑单元表示）。此值不能为 NULL。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

此成员函数模拟 GetTextExtentExPointI 函数的功能，如 Windows SDK 中所述。

`CDC::GetTextExtentPointI`

检索指定字形索引数组的宽度和高度。

BOOL GetTextExtentPointI(
    LPWORD pgiIn,
    int cgi,
    LPSIZE lpSize) const;

参数

pgiIn
指向要检索其范围的字形索引数组的指针。

cgi
指定 pgiIn 指向的数组中字形的数量。

lpSize
指向 SIZE 结构的指针，该结构接收字形索引数组的维度（以逻辑单元表示）。此值不能为 NULL。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

此成员函数模拟 GetTextExtentPointI 函数的功能，如 Windows SDK 中所述。

`CDC::GetTextFace`

调用此成员函数将当前字体的字样名称复制到缓冲区中。

int GetTextFace(
    int nCount,
    LPTSTR lpszFacename) const;

int GetTextFace(CString& rString) const;

参数

nCount
指定缓冲区的大小（以字节为单位）。如果字样名称长于此参数指定的字节数，则名称将被截断。

lpszFacename
指向字样名称的缓冲区。

rString
对 CString 对象的引用。

返回值

复制到缓冲区的字节数，不包括终止空字符。如果发生错误，则为 0。

备注

字样名称将作为 null 终止的字符串复制。

`CDC::GetTextMetrics`

使用属性设备上下文检索当前字体的指标。

BOOL GetTextMetrics(LPTEXTMETRIC lpMetrics) const;

参数

lpMetrics
指向接收指标的 TEXTMETRIC 结构。

返回值

如果该函数成功，则为非 0；否则为 0。

`CDC::GetViewportExt`

检索设备上下文视区的 x 范围和 y 范围。

CSize GetViewportExt() const;

返回值

作为 CSize 对象的 x 范围和 y 范围（以设备单元表示）。

`CDC::GetViewportOrg`

检索与设备上下文关联的视区原点的 x 坐标和 y 坐标。

CPoint GetViewportOrg() const;

返回值

作为 CPoint 对象的视区原点（以设备坐标表示）。

`CDC::GetWindow`

返回与显示设备上下文关联的窗口。

CWnd* GetWindow() const;

返回值

如果成功，则为指向 CWnd 对象的指针；否则为 NULL。

备注

这是一个高级函数。例如，此成员函数在打印或打印预览时可能不会返回视图窗口。它始终返回与输出关联的窗口。使用给定 DC 的输出函数绘制到此窗口中。

`CDC::GetWindowExt`

检索与设备上下文关联的窗口的 x 范围和 y 范围。

CSize GetWindowExt() const;

返回值

作为 CSize 对象的 x 范围和 y 范围（以逻辑单元表示）。

`CDC::GetWindowOrg`

检索与设备上下文关联的窗口原点的 x 坐标和 y 坐标。

CPoint GetWindowOrg() const;

返回值

作为 CPoint 对象的窗口原点（以逻辑坐标表示）。

`CDC::GetWorldTransform`

检索当前世界空间到页面空间的转换。

BOOL GetWorldTransform(XFORM& rXform) const;

参数

rXform
对接收当前世界空间到页面空间转换的 XFORM 结构的引用。

返回值

成功时返回一个非零值。

失败时返回 0。

若要获得扩展的错误信息，请调用 GetLastError。

备注

此方法包装 Windows GDI 函数 GetWorldTransform。

`CDC::GradientFill`

调用此成员函数，以使用从一侧平滑淡化到另一侧的颜色填充矩形和三角形结构。

BOOL GradientFill(
    TRIVERTEX* pVertices,
    ULONG nVertices,
    void* pMesh,
    ULONG nMeshElements,
    DWORD dwMode);

参数

pVertices
指向 TRIVERTEX 结构数组的指针，每个结构都定义一个三角形顶点。

nVertices
顶点数。

pMesh
三角形模式的 GRADIENT_TRIANGLE 结构数组，或矩形模式的 GRADIENT_RECT 结构数组。

nMeshElements
pMesh 中的元素（三角形或矩形）数。

dwMode
指定渐变填充模式。有关可能值的列表，请参阅 Windows SDK 中的 GradientFill。

返回值

如果成功，则返回 TRUE；否则返回 FALSE。

备注

有关详细信息，请参阅 Windows SDK 中的 GradientFill。

`CDC::GrayString`

通过将文本写入内存位图中，使位图变暗，然后将位图复制到显示器，在给定位置绘制变暗（灰色）文本。

virtual BOOL GrayString(
    CBrush* pBrush,
    BOOL (CALLBACK* lpfnOutput)(
    HDC,
    LPARAM,
    int),
    LPARAM lpData,
    int nCount,
    int x,
    int y,
    int nWidth,
    int nHeight);

参数

pBrush
标识要用于变暗（变灰）的画笔。

lpfnOutput
指定将绘制字符串的应用程序提供的回调函数的过程实例地址。有关详细信息，请参阅 Windows OutputFunc回调函数的说明。如果此参数为 NULL，则系统使用 Windows 的 TextOut 函数来绘制字符串，并且假设 lpData 是一个指向要输出的字符串的长指针。

lpData
指定要传递给输出函数的数据的远指针。如果 lpfnOutput 是 NULL，则 lpData 必须是指向要输出的字符串的长指针。

nCount
指定要输出的字符数。如果此参数为 0，则 GrayString 计算字符串的长度（假设 lpData 是指向字符串的指针）。如果 nCount 为 1，并且 lpfnOutput 指向的函数返回 0，则显示图像但不变暗。

x
指定包围字符串的矩形起始位置的逻辑 x 坐标。

y
指定包围字符串的矩形起始位置的逻辑 y 坐标。

nWidth
指定包围字符串的矩形的宽度（以逻辑单元表示）。如果 nWidth 为 0，则 GrayString 计算区域的宽度，假设 lpData 是指向字符串的指针。

nHeight
指定包围字符串的矩形的高度（以逻辑单元表示）。如果 nHeight 为 0，则 GrayString 计算区域的高度，假设 lpData 是指向字符串的指针。

返回值

如果绘制字符串，则为非零；如果 TextOut 函数或应用程序提供的输出函数返回 0，或者如果没有足够的内存来创建用于变暗的内存位图，则为 0。

备注

无论选择的画笔和背景如何，该函数都会使文本变暗。 GrayString 成员函数使用当前选择的字体。使用此函数前必须选择 MM_TEXT 映射模式。

应用程序可以在支持纯灰色的设备上绘制变暗（灰色）的字符串，而无需调用 GrayString 成员函数。系统颜色 COLOR_GRAYTEXT 是用于绘制禁用文本的纯灰色系统颜色。应用程序可以调用 GetSysColor Windows 函数来检索 COLOR_GRAYTEXT 的颜色值。如果颜色不是 0（黑色），应用程序可以调用 SetTextColor 成员函数以将文本颜色设置为该颜色值，然后直接绘制字符串。如果检索到的颜色为黑色，则应用程序必须调用 GrayString 以使文本变暗（变成灰色）。

如果 lpfnOutput 是 NULL，则 GDI 使用 Windows TextOut 函数，并且假定 lpData 是指向要输出的字符的远指针。如果 TextOut 成员函数无法处理要输出的字符（例如，字符串存储为位图），则应用程序必须提供自己的输出函数。

所有回调函数必须在返回到 Windows 之前捕获 Microsoft Foundation 异常，因为无法跨回调边界引发异常。有关异常的详细信息，请参阅异常一文。

传递给 GrayString 的回调函数必须使用 __stdcall 调用约定，并且必须使用 __declspec 导出。

当框架处于预览模式时，对 GrayString 成员函数的调用将转换为 TextOut 调用，并且不会调用回调函数。

`CDC::HIMETRICtoDP`

将 HIMETRIC 大小从 OLE 转换为像素时，使用此函数。

void HIMETRICtoDP(LPSIZE lpSize) const;

参数

lpSize
指向 SIZE 结构或 CSize 对象。

注解

`CDC::HIMETRICtoLP`

调用此函数可将 HIMETRIC 单元转换为逻辑单元。

void HIMETRICtoLP(LPSIZE lpSize) const;

参数

lpSize
指向 SIZE 结构或 CSize 对象。

注解

从 OLE 获得 HIMETRIC 大小并希望将它们转换为应用程序的自然映射模式时，使用此函数。

通过以下步骤完成转换：首先将 HIMETRIC 单元转换为像素，然后使用设备上下文的当前映射单元将这些单元转换为逻辑单元。请注意，设备窗口和视区的范围会影响结果。

`CDC::IntersectClipRect`

通过形成当前区域与 x1、y1、x2 和 y2 指定的矩形的交集来创建新的剪切区域。

int IntersectClipRect(
    int x1,
    int y1,
    int x2,
    int y2);

int IntersectClipRect(LPCRECT lpRect);

参数

x1
指定矩形左上角的逻辑 x 坐标。

y1
指定矩形左上角的逻辑 y 坐标。

x2
指定矩形右下角的逻辑 x 坐标。

y2
指定矩形右下角的逻辑 y 坐标。

lpRect
指定矩形。可以为此参数传递 CRect 对象或指向 RECT 结构的指针。

返回值

新剪切区域的类型。可以是以下任一值：

COMPLEXREGION 新剪切区域有重叠的边框。
ERROR 设备上下文无效。
NULLREGION 新剪切区域为空。
SIMPLEREGION 新剪切区域没有重叠的边框。

备注

GDI 将剪裁所有后续输出以适应新边界。宽度和高度不得超过 32,767。

`CDC::InvertRect`

反转给定矩形的内容。

void InvertRect(LPCRECT lpRect);

参数

lpRect
指向包含要反转的矩形的逻辑坐标的 RECT。还可以为此参数传递一个 CRect 对象。

备注

反转是一种逻辑“非”运算并翻转每个像素的位。在单色显示器上，该函数使白色像素变为黑色，并使黑色像素变为白色。在彩色显示器上，反转取决于为显示器生成颜色的方式。对同一个矩形调用两次 InvertRect 会将显示器还原到其以前的颜色。

如果矩形为空，则不会绘制任何内容。

示例

void CDCView::DoInvertRect(CDC *pDC)
{
   // invert rect from 20,20 to 50,50
   CRect rect(20, 20, 50, 50);
   pDC->InvertRect(rect);

   // inverting again restores to normal
   ::Sleep(1000);
   pDC->InvertRect(rect);
}

`CDC::InvertRgn`

反转由 pRgn 指定的区域中的颜色。

BOOL InvertRgn(CRgn* pRgn);

参数

pRgn
标识要反转的区域。区域的坐标以逻辑单元指定。

返回值

如果该函数成功，则为非 0；否则为 0。

注解

在单色显示器上，该函数使白色像素变为黑色，并使黑色像素变为白色。在彩色显示器上，反转取决于为显示器生成颜色的方式。

`CDC::IsPrinting`

确定设备上下文是否用于打印。

BOOL IsPrinting() const;

返回值

如果 CDC 对象是打印机 DC，则为非零；否则为 0。

`CDC::LineTo`

从当前位置绘制一条直到（但不包括）x 和 y（或 point）指定的点的线条。

BOOL LineTo(
    int x,
    int y);

BOOL LineTo(POINT point);

参数

x
指定线的端点的逻辑 x 坐标。

y
指定线的端点的逻辑 y 坐标。

point
指定线的端点。可以为此参数传递 POINT 结构或 CPoint 对象。

返回值

如果绘制线条，则为非零；否则为 0。

注解

使用所选触笔绘制线条。当前位置设置为 x、y 或 point。

示例

请参阅 CRect::CenterPoint 的示例。

`CDC::LPtoDP`

将逻辑单元转换为设备单元。

void LPtoDP(
    LPPOINT lpPoints,
    int nCount = 1) const;

void LPtoDP(LPRECT lpRect) const;
void LPtoDP(LPSIZE lpSize) const;

参数

lpPoints
指向点数组。数组中的每个点都是一个 POINT 结构或一个 CPoint 对象。

nCount
数组中的点数。

lpRect
指向 RECT 结构或 CRect 对象。此参数用于将矩形从逻辑单元映射到设备单元的常见情况。

lpSize
指向 SIZE 结构或 CSize 对象。

备注

该函数将每个点的坐标或大小的维度从 GDI 的逻辑坐标系映射到设备坐标系。转换取决于当前映射模式以及设备的窗口和视区的原点和范围的设置。

点的 x 坐标和 y 坐标是 -32,768 到 32,767 范围内的 2 字节带符号整数。如果映射模式会导致值大于这些限制，系统会将值分别设置为 -32,768 和 32,767。

`CDC::LPtoHIMETRIC`

调用此函数可将逻辑单元转换为 HIMETRIC 单元。

void LPtoHIMETRIC(LPSIZE lpSize) const;

参数

lpSize
指向 SIZE 结构或 CSize 对象。

备注

为 OLE 提供 HIMETRIC 大小时使用此函数，从应用程序的自然映射模式转换。设备窗口和视区的范围会影响结果。

通过以下步骤完成转换：首先使用设备上下文的当前映射单元将逻辑单元转换为像素，然后将这些单元转换为 HIMETRIC 单元。

`CDC::m_hAttribDC`

此 CDC 对象的属性设备上下文。

HDC m_hAttribDC;

注解

默认情况下，此设备上下文等于 m_hDC。通常，从设备上下文请求信息的 CDC GDI 调用被定向到 m_hAttribDC。有关使用这两个设备上下文的详细信息，请参阅 CDC 类说明。

`CDC::m_hDC`

此 CDC 对象的输出设备上下文。

HDC m_hDC;

备注

默认情况下，m_hDC 等于 m_hAttribDC，即由 CDC 包装的另一个设备上下文。通常，创建输出的 CDC GDI 调用将转到 m_hDC 设备上下文。可以初始化 m_hDC 和 m_hAttribDC 以指向不同的设备。有关使用这两个设备上下文的详细信息，请参阅 CDC 类说明。

`CDC::MaskBlt`

使用给定的蒙板和光栅操作组合源位图和目标位图的颜色数据。

BOOL MaskBlt(
    int x,
    int y,
    int nWidth,
    int nHeight,
    CDC* pSrcDC,
    int xSrc,
    int ySrc,
    CBitmap& maskBitmap,
    int xMask,
    int yMask,
    DWORD dwRop);

参数

x
指定目标矩形左上角的逻辑 x 坐标。

y
指定目标矩形左上角的逻辑 y 坐标。

nWidth
指定目标矩形和源位图的宽度（以逻辑单元表示）。

nHeight
指定目标矩形和源位图的高度（以逻辑单元表示）。

pSrcDC
标识要从中复制位图的设备上下文。如果 dwRop 参数指定不包含源的栅格操作，则它必须为 0。

xSrc
指定源位图左上角的逻辑 x 坐标。

ySrc
指定源位图左上角的逻辑 y 坐标。

maskBitmap
标识与源设备上下文中的颜色位图组合的单色掩码位图。

xMask
指定 maskBitmap 参数指定的掩码位图的水平像素偏移量。

yMask
指定 maskBitmap 参数指定的掩码位图的垂直像素偏移量。

dwRop
指定前景和背景三元光栅操作代码，该函数使用这些操作代码来控制源数据和目标数据的组合。背景光栅操作码存储在此值高位字的高位字节中；前景光栅操作码存储在此值高位字的低字节中；此值的低位字被忽略，应为 0。宏 MAKEROP4 创建前景和背景光栅操作代码的此类组合。有关此函数上下文中前景和背景的讨论，请参阅“注解”部分。有关常见光栅操作代码的列表，请参阅 BitBlt 成员函数。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

maskBitmap 指定的掩码中的值 1 表示应在该位置应用 dwRop 指定的前景光栅操作代码。掩码中的值 0 表示应在该位置应用 dwRop 指定的背景光栅操作代码。如果光栅操作需要源，则掩码矩形必须覆盖源矩形。否则，该函数将失败。如果光栅操作不需要源，则掩码矩形必须覆盖目标矩形。否则，该函数将失败。

如果调用此函数时源设备上下文的旋转或扭曲转换有效，则会发生错误。但是，允许其他类型的转换。

如果源位图、图案位图和目标位图的颜色格式不同，则此函数转换图案和/或源格式以匹配目标格式。如果掩码位图不是单色位图，则会发生错误。记录增强型图元文件时，如果源设备上下文标识增强型图元文件设备上下文，则会发生错误（并且函数返回 0）。并非所有设备都支持 MaskBlt。应用程序应调用 GetDeviceCaps 以确定设备是否支持此函数。如果未提供掩码位图，则此函数的行为与 BitBlt 完全相同，使用前景光栅操作代码。掩码位图中的像素偏移映射到源设备上下文位图中的点 (0,0)。这对于掩码位图包含一组掩码的情况很有用；通过调整发送到 MaskBlt 的像素偏移和矩形大小，应用程序可以轻松地将其中任何一个应用到掩码块传输任务。

`CDC::ModifyWorldTransform`

使用指定模式更改设备上下文的世界转换。

BOOL ModifyWorldTransform(
    const XFORM& rXform,
    DWORD iMode);

参数

rXform
对用于修改给定设备上下文的世界转换的 XFORM 结构的引用。

iMode
指定转换数据如何修改当前世界转换。有关此参数可以采用的值的列表，请参阅 ModifyWorldTransform。

返回值

成功时返回一个非零值。

失败时返回 0。

若要获得扩展的错误信息，请调用 GetLastError。

备注

此方法包装 Windows GDI 函数 ModifyWorldTransform。

`CDC::MoveTo`

将当前位置移动到 x 和 y（或 point）指定的点。

CPoint MoveTo(
    int x,
    int y);

CPoint MoveTo(POINT point);

参数

x
指定新位置的逻辑 x 坐标。

y
指定新位置的逻辑 y 坐标。

point
指定新位置。可以为此参数传递 POINT 结构或 CPoint 对象。

返回值

作为 CPoint 对象的前一个位置的 x 坐标和 y 坐标。

示例

请参阅 CRect::CenterPoint 的示例。

`CDC::OffsetClipRgn`

将设备上下文的剪切区域移动指定的偏移量。

int OffsetClipRgn(
    int x,
    int y);

int OffsetClipRgn(SIZE size);

参数

x
指定要向左或向右移动的逻辑单元数。

y
指定要向上或向下移动的逻辑单元数。

size
指定偏移量。

返回值

新区域的类型。可以是以下任一值：

COMPLEXREGION 剪切区域有重叠的边框。
ERROR 设备上下文无效。
NULLREGION 剪切区域为空。
SIMPLEREGION 剪切区域没有重叠的边框。

注解

该函数将区域沿 x 轴移动 x 个单元，沿 y 轴移动 y 个单元。

`CDC::OffsetViewportOrg`

相对于当前视区原点的坐标修改视区原点的坐标。

virtual CPoint OffsetViewportOrg(
    int nWidth,
    int nHeight);

参数

nWidth
指定要添加到当前原点 x 坐标的设备单元数。

nHeight
指定要添加到当前原点 y 坐标的设备单元数。

返回值

作为 CPoint 对象的前一个视区原点（以设备坐标表示）。

`CDC::OffsetWindowOrg`

相对于当前窗口原点的坐标修改窗口原点的坐标。

CPoint OffsetWindowOrg(
    int nWidth,
    int nHeight);

参数

nWidth
指定要添加到当前原点 x 坐标的逻辑单元数。

nHeight
指定要添加到当前原点 y 坐标的逻辑单元数。

返回值

作为 CPoint 对象的前一个窗口原点（以逻辑坐标表示）。

`CDC::operator HDC`

使用此运算符检索 CDC 对象的设备上下文句柄。

operator HDC() const;

返回值

如果成功，返回值为设备上下文对象的句柄；否则，为 NULL。

备注

可以使用句柄直接调用 Windows API。

`CDC::PaintRgn`

使用当前画笔填充 pRgn 指定的区域。

BOOL PaintRgn(CRgn* pRgn);

参数

pRgn
标识要填充的区域。给定区域的坐标以逻辑单元指定。

返回值

如果该函数成功，则为非 0；否则为 0。

`CDC::PatBlt`

在设备上创建位模式。

BOOL PatBlt(
    int x,
    int y,
    int nWidth,
    int nHeight,
    DWORD dwRop);

参数

x
指定要接收模式的矩形左上角的逻辑 x 坐标。

y
指定要接收模式的矩形左上角的逻辑 y 坐标。

nWidth
指定要接收模式的矩形的宽度（以逻辑单元表示）。

nHeight
指定要接收模式的矩形的高度（以逻辑单元表示）。

dwRop
指定光栅操作代码。光栅操作代码 (ROP) 定义 GDI 如何合并涉及当前画笔、可能的源位图和目标位图的输出操作中的颜色。此参数可能是以下值之一：

PATCOPY 将图案复制到目标位图。
PATINVERT 使用布尔 XOR (^) 运算符将目标位图与图案相结合。
DSTINVERT 反转目标位图。
BLACKNESS 将所有输出变为黑色。
WHITENESS 将所有输出变为白色。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

该图案是所选画笔和设备上已有图案的组合。 dwRop 指定的光栅操作代码定义如何组合图案。为此函数列出的光栅操作是完整 256 个三元光栅操作代码的有限子集；特别是，不能使用引用源的光栅操作代码。

并非所有设备上下文都支持 PatBlt 函数。若要确定设备上下文是否支持 PatBlt，请使用 RASTERCAPS 索引调用 GetDeviceCaps 成员函数并检查 RC_BITBLT 标志的返回值。

`CDC::Pie`

通过绘制一个椭圆弧来绘制一个饼形楔形，该椭圆弧的中心和两个端点由线条连接。

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);

参数

x1
指定边框左上角的 x 坐标（以逻辑单元表示）。

y1
指定边框左上角的 y 坐标（以逻辑单元表示）。

x2
指定边框右下角的 x 坐标（以逻辑单元表示）。

y2
指定边框右下角的 y 坐标（以逻辑单元表示）。

x3
指定弧线起点的 x 坐标（以逻辑单元表示）。此点不必完全位于弧线上。

y3
指定弧线起点的 y 坐标（以逻辑单元表示）。此点不必完全位于弧线上。

x4
指定弧线终点的 x 坐标（以逻辑单元表示）。此点不必完全位于弧线上。

y4
指定弧线终点的 y 坐标（以逻辑单元表示）。此点不必完全位于弧线上。

lpRect
指定边框。可以为此参数传递 CRect 对象或指向 RECT 结构的指针。

ptStart
指定弧线的起点。此点不必完全位于弧线上。可以为此参数传递 POINT 结构或 CPoint 对象。

ptEnd
指定弧线的终结点。此点不必完全位于弧线上。可以为此参数传递 POINT 结构或 CPoint 对象。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

弧线的中心是由 x1、y1、x2 和 y2（或 lpRect）指定的边框的中心。弧线的起点和终点由 x3、y3、x4 和 y4（或 ptStart 和 ptEnd）指定。

使用选定的触笔绘制弧线，沿逆时针方向移动。再从每个端点到弧线中心绘制两条线。饼形区域使用当前画笔填充。如果 x3 等于 x4 且 y3 等于 y4，则结果是一个椭圆形，从椭圆形的中心到点 (x3, y3) 或 (x4, y4) 有一条线。

此函数绘制的图形向上延伸到（但不包括）右侧和底部坐标。这意味着图形的高度是 y2 - y1，图形的宽度是 x2 - x1。边框的宽度和高度都必须大于 2 个单元且小于 32,767 个单元。

示例

void CDCView::DrawPie(CDC *pDC)
{
   // Fill the client area with a simple pie chart. A
   // big blue slice covers 75% of the pie, from
   // 6 o'clock to 3 o'clock. This portion is filled
   // with blue and has a blue edge. The remaining 25%
   // is filled with a red, diagonal hatch and has
   // a red edge.

   // Get the client area.
   CRect rectClient;
   GetClientRect(rectClient);

   // Make a couple of pens and similar brushes.
   CPen penBlue, penRed;
   CBrush brushBlue, brushRed;
   CBrush *pOldBrush;
   CPen *pOldPen;

   brushBlue.CreateSolidBrush(RGB(0, 0, 255));
   brushRed.CreateHatchBrush(HS_FDIAGONAL, RGB(255, 0, 0));
   penBlue.CreatePen(PS_SOLID | PS_COSMETIC, 1, RGB(0, 0, 255));
   penRed.CreatePen(PS_SOLID | PS_COSMETIC, 1, RGB(255, 0, 0));

   // Draw from 3 o'clock to 6 o'clock, counterclockwise,
   // in a blue pen with a solid blue fill.

   pOldPen = pDC->SelectObject(&penBlue);
   pOldBrush = pDC->SelectObject(&brushBlue);

   pDC->Pie(rectClient,
            CPoint(rectClient.right, rectClient.CenterPoint().y),
            CPoint(rectClient.CenterPoint().x, rectClient.right));

   // Draw the remaining quarter slice from 6 o'clock
   // to 3 o'clock, counterclockwise, in a red pen with
   // the hatched brush.
   pDC->SelectObject(&penRed);
   pDC->SelectObject(&brushRed);

   // Same parameters, but reverse start and end points.
   pDC->Pie(rectClient,
            CPoint(rectClient.CenterPoint().x, rectClient.right),
            CPoint(rectClient.right, rectClient.CenterPoint().y));

   // Restore the previous pen.
   pDC->SelectObject(pOldPen);
}

`CDC::PlayMetaFile`

在设备上下文上播放指定图元文件的内容。

BOOL PlayMetaFile(HMETAFILE hMF);

BOOL PlayMetaFile(
    HENHMETAFILE hEnhMetaFile,
    LPCRECT lpBounds);

参数

hMF
标识要播放的图元文件。

hEnhMetaFile
标识增强型图元文件。

lpBounds
指向包含用于显示图片的边框坐标的 RECT 结构或 CRect 对象。坐标以逻辑单元指定。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

可以任意次数播放图元文件。

PlayMetaFile 的第二个版本显示存储在给定增强格式图元文件中的图片。当应用程序调用 PlayMetaFile 的第二个版本时，Windows 使用增强型图元文件标头中的图片框将图片映射到 lpBounds 参数指向的矩形上。（通过在调用 PlayMetaFile 之前在输出设备中设置世界转换，可以扭曲或旋转此图片。）沿矩形边缘的点包含在图片中。可以通过在播放增强型图元文件之前在输出设备中定义剪切区域来剪裁增强型图元文件图片。

如果增强型图元文件包含可选调色板，则应用程序可以通过在调用 PlayMetaFile 的第二个版本之前在输出设备上设置调色板来实现一致的颜色。若要检索可选调色板，请使用 GetEnhMetaFilePaletteEntries Windows 函数。通过调用 PlayMetaFile 的第二个版本并将源增强型图元文件播放到新增强型图元文件的设备上下文中，可以将增强型图元文件嵌入到新创建的增强型图元文件中。

此函数保留输出设备上下文的状态。在增强型图元文件中创建但未删除的任何对象都被此函数删除。若要停止此函数，应用程序可以从另一个线程调用 CancelDC Windows 函数来终止操作。在这种情况下，该函数返回 0。

`CDC::PlgBlt`

执行颜色数据位的位块传输，从源设备上下文中的指定矩形传输到给定设备上下文中的指定平行四边形。

BOOL PlgBlt(
    LPPOINT lpPoint,
    CDC* pSrcDC,
    int xSrc,
    int ySrc,
    int nWidth,
    int nHeight,
    CBitmap& maskBitmap,
    int xMask,
    int yMask);

参数

lpPoint
指向逻辑空间中三个点的数组，该数组标识目标平行四边形的三个角。源矩形的左上角映射到此数组的第一个点，右上角映射到此数组的第二个点，左下角映射到第三个点。源矩形的右下角映射到平行四边形中隐含的第四个点。

pSrcDC
标识源设备上下文。

xSrc
指定源矩形左上角的 x 坐标（以逻辑单元表示）。

ySrc
指定源矩形左上角的 y 坐标（以逻辑单元表示）。

nWidth
指定源矩形的宽度（以逻辑单元表示）。

nHeight
指定源矩形的高度（以逻辑单元表示）。

maskBitmap
标识用于屏蔽源矩形颜色的可选单色位图。

xMask
指定单色位图左上角的 x 坐标。

yMask
指定单色位图左上角的 y 坐标。

返回值

如果该函数成功，则为非 0；否则为 0。

注解

如果给定的位掩码句柄标识有效的单色位图，则该函数使用此位图来屏蔽源矩形中的颜色数据位。

平行四边形 (D) 的第四个顶点通过将前三个点（A、B 和 C）视为向量并计算 D = B + C - A 来定义。

如果位掩码存在，掩码中的值 1 表示应将源像素颜色复制到目标。掩码中的值 0 表示不更改目标像素颜色。

如果掩码矩形小于源矩形和目标矩形，则该函数将复制掩码图案。

源设备上下文中允许缩放、转换和反射转换；但是，不允许旋转和扭曲转换。如果掩码位图不是单色位图，则会发生错误。目标设备上下文的拉伸模式用于确定如何拉伸或压缩像素（如果有必要）。记录增强型图元文件时，如果源设备上下文标识增强型图元文件设备上下文，则会发生错误。

目标坐标将根据目标设备上下文进行转换；源坐标将根据源设备上下文进行转换。如果源转换有旋转或扭曲，则返回错误。如果目标矩形和源矩形的颜色格式不同，PlgBlt 将转换源矩形以匹配目标矩形。并非所有设备都支持 PlgBlt。有关详细信息，请参阅 CDC::GetDeviceCaps 成员函数中的 RC_BITBLT 光栅功能的说明。

如果源设备上下文和目标设备上下文表示不兼容的设备，PlgBlt 将返回错误。

`CDC::PolyBezier`

绘制一条或多条贝塞尔曲线。

BOOL PolyBezier(
    const POINT* lpPoints,
    int nCount);

参数

lpPoints
指向包含曲线端点和控制点的 POINT 数据结构数组。

nCount
指定 lpPoints 数组中的点数。此值必须是要绘制的曲线数的三倍以上，因为每个贝塞尔曲线都需要两个控制点和一个端点，而初始曲线还需要一个起点。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

此函数使用 lpPoints 参数指定的端点和控制点绘制三次方贝塞尔曲线。使用第二和第三点作为控制点，从第一点到第四点绘制第一条曲线。序列中的每个后续曲线都需要另外三个点：前一条曲线的终点用作起点，序列中接下来的两个点是控制点，第三个点是终点。

PolyBezier 函数既不使用也不更新当前位置。该图形未填充。此函数使用当前触笔绘制线条。

`CDC::PolyBezierTo`

绘制一条或多条贝塞尔曲线。

BOOL PolyBezierTo(
    const POINT* lpPoints,
    int nCount);

参数

lpPoints
指向包含端点和控制点的 POINT 数据结构数组。

nCount
指定 lpPoints 数组中的点数。此值必须是要绘制的曲线数的三倍，因为每个贝塞尔曲线都需要两个控制点和一个端点。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

此函数使用 lpPoints 参数指定的控制点绘制三次方贝塞尔曲线。第一条曲线以前两个点为控制点，从当前位置绘制到第三个点。对于每个后续曲线，该函数恰好需要另外三个点，并使用前一条曲线的终点作为下一条曲线的起点。 PolyBezierTo 将当前位置移动到最后一条贝塞尔曲线的终点。该图形未填充。此函数使用当前触笔绘制线条。

示例

请参阅 CDC::BeginPath 的示例。

`CDC::PolyDraw`

绘制一组线段和贝塞尔曲线。

BOOL PolyDraw(
    const POINT* lpPoints,
    const BYTE* lpTypes,
    int nCount);

参数

lpPoints
指向 POINT 数据结构数组，其中包含每个线段的端点以及每条贝塞尔曲线的端点和控制点。

lpTypes
指向一个数组，该数组指定如何使用 lpPoints 数组中的每个点。可以是下列值之一：

PT_MOVETO 指定此点开始一个不相交的图形。此点将成为新的当前位置。
PT_LINETO 指定从当前位置到此点绘制一条线，然后此点将成为新的当前位置。
PT_BEZIERTO 指定此点是贝塞尔曲线的控制点或终点。

PT_BEZIERTO 类型总是以三个一组出现。当前位置定义贝塞尔曲线的起点。前两个 PT_BEZIERTO 点是控制点，第三个 PT_BEZIERTO 点是终点。终点将成为新的当前位置。如果没有三个连续 PT_BEZIERTO 点，则会导致错误。

PT_LINETO 或 PT_BEZIERTO 类型可以通过使用按位运算符 OR 与以下常量组合，以指示对应点是图形中的最后一个点并且图形是闭合的：

PT_CLOSEFIGURE 指定在此点的 PT_LINETO 或 PT_BEZIERTO 类型完成后自动闭合图形。从此点到最近的 PT_MOVETO 或 MoveTo 点绘制一条线。

通过使用按位 OR 运算符，此标志与线条的 PT_LINETO 类型或贝塞尔曲线终点的 PT_BEZIERTO 类型组合。当前位置设置为闭合线的终点。

nCount
指定 lpPoints 数组中的总点数，与 lpTypes 数组中的字节数相同。

返回值

如果该函数成功，则为非 0；否则为 0。

注解

此函数可用于绘制不相交的图形，以代替对 CDC::MoveTo、CDC::LineTo 和 CDC::PolyBezierTo 成员函数的连续调用。线条和曲线是使用当前触笔绘制的，并且没有填充图形。如果存在通过调用 CDC::BeginPath 成员函数启动的活动路径，则 PolyDraw 将添加到路径中。 lpPoints 数组中和 lpTypes 中包含的点指示每个点是 CDC::MoveTo、CDC::LineTo 还是 CDC::BezierTo 操作的一部分。也可以闭合图形。此函数更新当前位置。

示例

请参阅 CDC::BeginPath 的示例。

`CDC::Polygon`

使用当前触笔绘制由通过线连接的两个或更多点（顶点）组成的多边形。

BOOL Polygon(
    LPPOINT lpPoints,
    int nCount);

参数

lpPoints
指向指定多边形顶点的点数组。数组中的每个点都是一个 POINT 结构或一个 CPoint 对象。

nCount
指定数组中的顶点数。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

如有必要，系统会通过从最后一个顶点到第一个顶点绘制一条线来自动闭合多边形。

可以使用 GetPolyFillMode 和 SetPolyFillMode 成员函数检索或设置当前的多边形填充模式。

示例

void CDCView::DrawPolygon(CDC *pDC)
{
   // find the client area
   CRect rect;
   GetClientRect(rect);

   // draw with a thick blue pen
   CPen penBlue(PS_SOLID, 5, RGB(0, 0, 255));
   CPen *pOldPen = pDC->SelectObject(&penBlue);

   // and a solid red brush
   CBrush brushRed(RGB(255, 0, 0));
   CBrush *pOldBrush = pDC->SelectObject(&brushRed);

   // Find the midpoints of the top, right, left, and bottom
   // of the client area. They will be the vertices of our polygon.
   CPoint pts[4];
   pts[0].x = rect.left + rect.Width() / 2;
   pts[0].y = rect.top;

   pts[1].x = rect.right;
   pts[1].y = rect.top + rect.Height() / 2;

   pts[2].x = pts[0].x;
   pts[2].y = rect.bottom;

   pts[3].x = rect.left;
   pts[3].y = pts[1].y;

   // Calling Polygon() on that array will draw three lines
   // between the points, as well as an additional line to
   // close the shape--from the last point to the first point
   // we specified.
   pDC->Polygon(pts, 4);

   // Put back the old objects.
   pDC->SelectObject(pOldPen);
   pDC->SelectObject(pOldBrush);
}

`CDC::Polyline`

绘制一组连接由 lpPoints 指定的点的线段。

BOOL Polyline(
    LPPOINT lpPoints,
    int nCount);

参数

lpPoints
指向要连接的 POINT 结构或 CPoint 对象的数组。

nCount`
指定数组中的点数。此值必须至少为 2。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

使用当前触笔从第一个点到后续点绘制线条。与 LineTo 成员函数不同，Polyline 函数既不使用也不更新当前位置。

有关详细信息，请参阅 Windows SDK 中的 PolyLine。

`CDC::PolylineTo`

绘制一条或多条直线。

BOOL PolylineTo(
    const POINT* lpPoints,
    int nCount);

参数

lpPoints
指向包含线条顶点的 POINT 数据结构数组。

nCount
指定数组中的点数。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

使用当前触笔从当前位置到 lpPoints 参数指定的第一个点绘制一条线。对于每条额外的线，该函数从前一条线的终点绘制到 lpPoints 指定的下一个点。 PolylineTo 将当前位置移动到最后一条线的终点。如果此函数绘制的线段形成一个闭合图形，则不会填充该图形。

`CDC::PolyPolygon`

创建两个或更多使用当前多边形填充模式填充的多边形。

BOOL PolyPolygon(
    LPPOINT lpPoints,
    LPINT lpPolyCounts,
    int nCount);

参数

lpPoints
指向定义多边形顶点的一组 POINT 结构或 CPoint 对象。

lpPolyCounts
指向整数数组，每个整数指定 lpPoints 数组中的一个多边形中的点数。

nCount
lpPolyCounts 数组中的条目数。此数字指定要绘制的多边形的数量。此值必须至少为 2。

返回值

如果该函数成功，则为非 0；否则为 0。

注解

这些多边形可能不相交，也可能重叠。

在调用 PolyPolygon 函数时指定的每个多边形都必须是闭合的。与 Polygon 成员函数创建的多边形不同，PolyPolygon 创建的多边形不会自动闭合。

该函数创建两个或更多个多边形。若要创建单个多边形，应用程序应使用 Polygon 成员函数。

可以使用 GetPolyFillMode 和 SetPolyFillMode 成员函数检索或设置当前的多边形填充模式。

`CDC::PolyPolyline`

绘制多个系列连接的线段。

BOOL PolyPolyline(
    const POINT* lpPoints,
    const DWORD* lpPolyPoints,
    int nCount);

参数

lpPoints
指向包含折线顶点的结构数组。折线是连续指定的。

lpPolyPoints
指向一个变量数组，指定 lpPoints 数组中相应多边形的点数。每个条目必须大于或等于 2。

nCount
指定 lpPolyPoints 数组中的总计数。

返回值

如果该函数成功，则为非 0；否则为 0。

注解

线段是使用当前触笔绘制的。由这些线段组成的图形未填充。此函数既不使用也不更新当前位置。

`CDC::PtVisible`

确定给定点是否在设备上下文的剪切区域内。

virtual BOOL PtVisible(
    int x,
    int y) const;

BOOL PtVisible(POINT point) const;

参数

x
指定点的逻辑 x 坐标。

y
指定点的逻辑 y 坐标。

point
指定要在逻辑坐标中检查的点。可以为此参数传递 POINT 结构或 CPoint 对象。

返回值

如果指定点在剪切区域内，则为非零；否则为 0。

`CDC::QueryAbort`

调用打印应用程序的 SetAbortProc 成员函数安装的中止函数，并查询是否应终止打印。

BOOL QueryAbort() const;

返回值

如果应继续打印或没有中止过程，则返回值为非零。如果应终止打印作业，则为 0。返回值由中止函数提供。

`CDC::RealizePalette`

将当前逻辑调色板中的条目映射到系统调色板。

UINT RealizePalette();

返回值

指示逻辑调色板中有多少条目映射到了系统调色板中的不同条目。这表示自上次实现逻辑调色板以来，此函数重新映射，以适应系统调色板中的更改的条目数。

备注

逻辑调色板充当颜色密集型应用程序和系统之间的缓冲区，允许应用程序根据需要使用尽可能多的颜色，而不会干扰其自己显示的颜色或由其他窗口显示的颜色。

当窗口具有输入焦点并调用 RealizePalette 时，Windows 会确保窗口将显示所有请求的颜色，直到屏幕上同时可用的最大数量。 Windows 还通过将它们与可用颜色匹配来显示在窗口的调色板中找不到的颜色。

此外，Windows 将调用该函数的非活动窗口请求的颜色与可用颜色尽可能匹配。这显著减少了非活动窗口中显示的颜色的不良变化。

`CDC::Rectangle`

使用当前触笔绘制矩形。

BOOL Rectangle(
    int x1,
    int y1,
    int x2,
    int y2);

BOOL Rectangle(LPCRECT lpRect);

参数

x1
指定矩形左上角的 x 坐标（以逻辑单元表示）。

y1
指定矩形左上角的 y 坐标（以逻辑单元表示）。

x2
指定矩形右下角的 x 坐标（以逻辑单元表示）。

y2
指定矩形右下角的 y 坐标（以逻辑单元表示）。

lpRect
指定矩形（以逻辑单元表示）。可以为此参数传递 CRect 对象或指向 RECT 结构的指针。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

使用当前画笔填充矩形的内部。

矩形延伸到（但不包括）右侧和底部坐标。这意味着矩形的高度是 y2 - y1，矩形的宽度是 x2 - x1。矩形的宽度和高度都必须大于 2 个单元且小于 32,767 个单元。

示例

void CDCView::DrawRectangle(CDC *pDC)
{
   // create and select a solid blue brush
   CBrush brushBlue(RGB(0, 0, 255));
   CBrush *pOldBrush = pDC->SelectObject(&brushBlue);

   // create and select a thick, black pen
   CPen penBlack;
   penBlack.CreatePen(PS_SOLID, 3, RGB(0, 0, 0));
   CPen *pOldPen = pDC->SelectObject(&penBlack);

   // get our client rectangle
   CRect rect;
   GetClientRect(rect);

   // shrink our rect 20 pixels in each direction
   rect.DeflateRect(20, 20);

   // draw a thick black rectangle filled with blue
   pDC->Rectangle(rect);

   // put back the old objects
   pDC->SelectObject(pOldBrush);
   pDC->SelectObject(pOldPen);
}

`CDC::RectVisible`

确定给定矩形的任何部分是否位于显示上下文的剪切区域内。

virtual BOOL RectVisible(LPCRECT lpRect) const;

参数

lpRect
指向包含指定矩形的逻辑坐标的 RECT 结构或 CRect 对象。

返回值

如果给定矩形的任何部分位于剪切区域内，则为非零；否则为 0。

`CDC::ReleaseAttribDC`

调用此成员函数将 m_hAttribDC 设置为 NULL。

virtual void ReleaseAttribDC();

注解

这不会导致发生 Detach。只有输出设备上下文附加到 CDC 对象，并且只有它可以分离。

`CDC::ReleaseOutputDC`

调用此成员函数将 m_hDC 成员设置为 NULL。

virtual void ReleaseOutputDC();

备注

当输出设备上下文附加到 CDC 对象时，无法调用此成员函数。使用 Detach 成员函数分离输出设备上下文。

`CDC::ResetDC`

调用此成员函数，以更新由 CDC 对象包装的设备上下文。

BOOL ResetDC(const DEVMODE* lpDevMode);

参数

lpDevMode
指向 Windows DEVMODE 结构的指针。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

设备上下文根据 Windows DEVMODE 结构中指定的信息进行更新。此成员函数仅重置属性设备上下文。

当窗口处理 WM_DEVMODECHANGE 消息时，应用程序通常会使用 ResetDC 成员函数。还可以使用此成员函数在打印文档时更改纸张方向或纸箱。

不能使用此成员函数来更改驱动程序名称、设备名或输出端口。当用户更改端口连接或设备名时，你必须删除原始设备上下文并使用新信息创建新的设备上下文。

在调用此成员函数之前，必须确保已选择进入设备上下文的所有对象（除了库存对象）都已被选中。

`CDC::RestoreDC`

将设备上下文恢复到 nSavedDC 标识的上一个状态。

virtual BOOL RestoreDC(int nSavedDC);

参数

nSavedDC
指定要恢复的设备上下文。它可以是上一个 SaveDC 函数调用返回的值。如果 nSavedDC 为 -1，则恢复最近保存的设备上下文。

返回值

如果指定的上下文已恢复，则为非零；否则为 0。

备注

RestoreDC 通过从先前调用 SaveDC 成员函数创建的堆栈中弹出状态信息来恢复设备上下文。

堆栈可以包含多个设备上下文的状态信息。如果 nSavedDC 指定的上下文不在堆栈顶部，则 RestoreDC 删除由 nSavedDC 指定的设备上下文和堆栈顶部之间的所有状态信息。已删除的信息丢失。

`CDC::RoundRect`

使用当前触笔绘制带圆角的矩形。

BOOL RoundRect(
    int x1,
    int y1,
    int x2,
    int y2,
    int x3,
    int y3);

BOOL RoundRect(
    LPCRECT lpRect,
    POINT point);

参数

x1
指定矩形左上角的 x 坐标（以逻辑单元表示）。

y1
指定矩形左上角的 y 坐标（以逻辑单元表示）。

x2
指定矩形右下角的 x 坐标（以逻辑单元表示）。

y2
指定矩形右下角的 y 坐标（以逻辑单元表示）。

x3
指定用于绘制圆角的椭圆形的宽度（以逻辑单元表示）。

y3
指定用于绘制圆角的椭圆形的高度（以逻辑单元表示）。

lpRect
指定边框（以逻辑单元表示）。可以为此参数传递 CRect 对象或指向 RECT 结构的指针。

point
point 的 x 坐标指定绘制圆角的椭圆形的宽度（以逻辑单元表示）。 point 的 y 坐标指定绘制圆角的椭圆形的高度（以逻辑单元表示）。可以为此参数传递 POINT 结构或 CPoint 对象。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

使用当前画笔填充矩形的内部。

此函数绘制的图形向上延伸到（但不包括）右侧和底部坐标。这意味着图形的高度是 y2 - y1，图形的宽度是 x2 - x1。边框的高度和宽度都必须大于 2 个单元且小于 32,767 个单元。

示例

void CDCView::DrawRoundRect(CDC *pDC)
{
   // create and select a solid blue brush
   CBrush brushBlue(RGB(0, 0, 255));
   CBrush *pOldBrush = pDC->SelectObject(&brushBlue);

   // create and select a thick, black pen
   CPen penBlack;
   penBlack.CreatePen(PS_SOLID, 3, RGB(0, 0, 0));
   CPen *pOldPen = pDC->SelectObject(&penBlack);

   // get our client rectangle
   CRect rect;
   GetClientRect(rect);

   // shrink our rect 20 pixels in each direction
   rect.DeflateRect(20, 20);

   // Draw a thick black rectangle filled with blue
   // corners rounded at a 17-unit radius. Note that
   // a radius of three or less is not noticeable because
   // the pen is three units wide.
   pDC->RoundRect(rect, CPoint(17, 17));

   // put back the old objects
   pDC->SelectObject(pOldBrush);
   pDC->SelectObject(pOldPen);
}

`CDC::SaveDC`

通过将状态信息（例如剪切区域、选定对象和映射模式）复制到由 Windows 维护的上下文堆栈来保存设备上下文的当前状态。

virtual int SaveDC();

返回值

一个整数，标识已保存的设备上下文。如果发生错误，则为 0。此返回值可用于通过调用 RestoreDC 来恢复设备上下文。

注解

稍后可以使用 RestoreDC 恢复已保存的设备上下文。

SaveDC 可以使用任意次数来保存任意数量的设备上下文状态。

`CDC::ScaleViewportExt`

相对于当前值修改视区范围。

virtual CSize ScaleViewportExt(
    int xNum,
    int xDenom,
    int yNum,
    int yDenom);

参数

xNum
指定与当前 x 范围相乘的数量。

xDenom
指定当前 x 范围乘以 xNum 参数值的结果将除以的数量。

yNum
指定与当前 y 范围相乘的数量。

yDenom
指定当前 y 范围乘以 yNum 参数值的结果将除以的数量。

返回值

作为 CSize 对象的先前视区范围（以单元表示）。

注解

公式按如下方式编写：

xNewVE = ( xOldVE * xNum ) / xDenom

yNewVE = ( yOldVE * yNum ) / yDenom

新视区范围的计算方法是将当前范围乘以给定的分子，然后除以给定的分母。

`CDC::ScaleWindowExt`

相对于当前值修改窗口范围。

virtual CSize ScaleWindowExt(
    int xNum,
    int xDenom,
    int yNum,
    int yDenom);

参数

xNum
指定与当前 x 范围相乘的数量。

xDenom
指定当前 x 范围乘以 xNum 参数值的结果将除以的数量。

yNum
指定与当前 y 范围相乘的数量。

yDenom
指定当前 y 范围乘以 yNum 参数值的结果将除以的数量。

返回值

作为 CSize 对象的先前窗口范围（以逻辑单元表示）。

备注

公式按如下方式编写：

xNewWE = ( xOldWE * xNum ) / xDenom

yNewWE = ( yOldWE * yNum ) / yDenom

新窗口范围的计算方法是将当前范围乘以给定的分子，然后除以给定的分母。

`CDC::ScrollDC`

水平和垂直滚动一个位矩形。

BOOL ScrollDC(
    int dx,
    int dy,
    LPCRECT lpRectScroll,
    LPCRECT lpRectClip,
    CRgn* pRgnUpdate,
    LPRECT lpRectUpdate);

参数

dx
指定水平滚动单元的数量。

dy
指定垂直滚动单元的数量。

lpRectScroll
指向包含滚动矩形坐标的 RECT 结构或 CRect 对象。

lpRectClip
指向包含剪切矩形坐标的 RECT 结构或 CRect 对象。当此矩形小于 lpRectScroll 指向的原始矩形时，滚动只发生在较小的矩形中。

pRgnUpdate
标识滚动过程未覆盖的区域。 ScrollDC 函数定义此区域；它不一定是矩形。

lpRectUpdate
指向接收限制滚动更新区域的矩形坐标的 RECT 结构或 CRect 对象。这是需要重新绘制的最大矩形区域。函数返回时结构或对象中的值以客户端坐标表示，无论给定设备上下文的映射模式如何。

返回值

如果执行滚动，则为非零；否则为 0。

备注

如果 lpRectUpdate 是 NULL，则 Windows 不会计算更新矩形。如果 pRgnUpdate 和 lpRectUpdate 都是 NULL，则 Windows 不会计算更新区域。如果 pRgnUpdate 不是 NULL，则 Windows 假定它包含一个有效指针，指向滚动进程（由 ScrollDC 成员函数定义）未覆盖的区域。如果需要，可以将 lpRectUpdate 中返回的更新区域传递给 CWnd::InvalidateRgn。

当需要滚动窗口的整个工作区时，应用程序应使用 CWnd 类的 ScrollWindow 成员函数。否则，它应使用 ScrollDC。

`CDC::SelectClipPath`

选择当前路径作为设备上下文的剪切区域，使用指定的模式将新区域与任何现有剪切区域组合。

BOOL SelectClipPath(int nMode);

参数

nMode
指定使用路径的方法。允许以下值：

RGN_AND 新剪切区域包括当前剪切区域和当前路径的交集（重叠区域）。
RGN_COPY 新剪切区域是当前路径。
RGN_DIFF 新剪切区域包括当前剪切区域的区域，不包括当前路径的区域。
RGN_OR 新剪切区域包括当前剪切区域和当前路径的并集（合并区域）。
RGN_XOR 新剪切区域包括当前剪切区域和当前路径的并集，但不包括重叠区域。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

标识的设备上下文必须包含封闭的路径。

`CDC::SelectClipRgn`

选择给定区域作为设备上下文的当前剪切区域。

int SelectClipRgn(CRgn* pRgn);

int SelectClipRgn(
    CRgn* pRgn,
    int nMode);

参数

pRgn
标识要选择的区域。

对于此函数的第一个版本，如果此值为 NULL，则选择整个工作区，并且输出仍被剪切到窗口。
对于此函数的第二个版本，只有在指定了 RGN_COPY 模式时，此句柄才能为 NULL。

nMode
指定要执行的操作。它必须是以下值之一：

RGN_AND 新剪切区域结合将当前剪切区域和 pRgn 标识的区域的重叠区域。
RGN_COPY 新剪切区域是由 pRgn 标识的区域的副本。此功能与 SelectClipRgn 的第一个版本相同。如果 pRgn 标识的区域为 NULL，则新剪切区域将成为默认剪切区域（null 区域）。
RGN_DIFF 新剪切区域将当前剪切区域的区域与从 pRgn 标识的区域中排除的区域相结合。
RGN_OR 新剪切区域将结合当前剪切区域和 pRgn 标识的区域。
RGN_XOR 新剪切区域将结合当前剪切区域和 pRgn 标识的区域，但不包括任何重叠区域。

返回值

区域的类型。可以是以下任一值：

COMPLEXREGION 新剪切区域有重叠的边框。
ERROR 设备上下文或区域无效。
NULLREGION 新剪切区域为空。
SIMPLEREGION 新剪切区域没有重叠的边框。

备注

仅使用所选区域的副本。可以为任意数量的其他设备上下文选择区域本身，也可以将其删除。

该函数假定给定区域的坐标以设备单元形式指定。一些打印机设备支持以比图形输出更高的分辨率输出文本，以便保留表达文本指标所需的精度。这些设备以更高的分辨率（即文本单元）报告设备单元。然后，这些设备缩放图形坐标，以便多个报告的设备单元仅映射到 1 个图形单元。应始终使用文本单元调用 SelectClipRgn 函数。

必须缩放 GDI 中的图形对象的应用程序可以使用 GETSCALINGFACTOR 打印机转义来确定缩放因子。此缩放因子会影响剪切。如果使用区域来剪裁图形，GDI 会将坐标除以缩放因子。如果区域用于剪裁文本，GDI 不会进行缩放调整。缩放因子为 1 会使坐标除以 2；缩放因子为 2 会使坐标除以 4；等等。

`CDC::SelectObject`

选择一个对象到设备上下文中。

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);

参数

pPen
指向要选择的 CPen 对象的指针。

pBrush
指向要选择的 CBrush 对象的指针。

pFont
指向要选择的 CFont 对象的指针。

pBitmap
指向要选择的 CBitmap 对象的指针。

pRgn
指向要选择的 CRgn 对象的指针。

pObject
指向要选择的 CGdiObject 对象的指针。

返回值

指向要替换的对象的指针。这是一个指向从 CGdiObject 派生的类之一的对象的指针，例如 CPen，具体取决于所使用的函数版本。如果有错误，则返回值为 NULL。此函数可能会返回一个指向临时对象的指针。此临时对象仅在处理一条 Windows 消息期间有效。有关详细信息，请参阅 CGdiObject::FromHandle。

采用区域参数的成员函数版本执行与 SelectClipRgn 成员函数相同的任务。其返回值可以是下列任意值：

COMPLEXREGION 新剪切区域有重叠的边框。
ERROR 设备上下文或区域无效。
NULLREGION 新剪切区域为空。
SIMPLEREGION 新剪切区域没有重叠的边框。

备注

类 CDC 提供了五个版本，专门用于特定种类的 GDI 对象，包括触笔、画笔、字体、位图和区域。新选择的对象将替换相同类型的先前对象。例如，如果 SelectObject 的常规版本的 pObject 指向 CPen 对象，则该函数会将当前触笔替换为 pObject 指定的触笔。

应用程序只能将位图选择到内存设备上下文中，并且一次只能选择到一个内存设备上下文中。位图的格式必须是单色的或与设备上下文兼容的；如果不是，则 SelectObject 会返回错误。

对于 Windows 3.1 和更高版本，无论是否在图元文件中使用，SelectObject 函数都会返回相同的值。在以前版本的 Windows 中，当在图元文件中使用 SelectObject 时，它返回一个非零值表示成功，返回 0 表示失败。

`CDC::SelectPalette`

选择由 pPalette 指定的逻辑调色板作为设备上下文的选定调色板对象。

CPalette* SelectPalette(
    CPalette* pPalette,
    BOOL bForceBackground);

参数

pPalette
标识要选择的逻辑调色板。此调色板必须已使用 CPalette 成员函数 CreatePalette 创建。

bForceBackground
指定逻辑调色板是否强制为背景调色板。如果 bForceBackground 为非零，则无论窗口是否具有输入焦点，所选调色板始终为背景调色板。如果 bForceBackground 为 0，并且设备上下文附加到窗口，则当窗口具有输入焦点时，逻辑调色板为前景调色板。

返回值

指向 CPalette 对象的指针，该对象标识由 pPalette 指定的调色板替换的逻辑调色板。如果有错误，则为 NULL。

备注

新的调色板将成为 GDI 用来控制在设备上下文中显示的颜色的调色板对象，并替换以前的调色板。

应用程序可以将逻辑调色板选择到多个设备上下文中。但是，对逻辑调色板的更改将影响选择它的所有设备上下文。如果应用程序将调色板选择到多个设备上下文中，则设备上下文必须都属于同一个物理设备。

`CDC::SelectStockObject`

选择与预定义的常用笔、画笔或字体之一相对应的 CGdiObject 对象。

virtual CGdiObject* SelectStockObject(int nIndex);

参数

nIndex
指定所需常用对象的类型。可以为下列值之一：

BLACK_BRUSH 黑色画笔。
DKGRAY_BRUSH 深灰色画笔。
GRAY_BRUSH 灰色画笔。
HOLLOW_BRUSH 空心画笔。
LTGRAY_BRUSH 浅灰色画笔。
NULL_BRUSH null 画笔。
WHITE_BRUSH 白色画笔。
BLACK_PEN 黑色触笔。
NULL_PEN null 触笔。
WHITE_PEN 白色触笔。
ANSI_FIXED_FONT ANSI 固定系统字体。
ANSI_VAR_FONT ANSI 可变系统字体。
DEVICE_DEFAULT_FONT 设备依赖字体。
OEM_FIXED_FONT OEM 依赖固定字体。
SYSTEM_FONT 系统字体。默认情况下，Windows 使用系统字体绘制菜单、对话框控件和其他文本。但是，最好不要依赖 SYSTEM_FONT 来获取对话框和窗口使用的字体。而是使用带有 SPI_GETNONCLIENTMETRICS 参数的 SystemParametersInfo 函数来检索当前字体。 SystemParametersInfo 考虑当前主题并为标题、菜单和消息对话框提供字体信息。
SYSTEM_FIXED_FONT 在版本 3.0 之前的 Windows 中使用的固定宽度系统字体。此对象可用于与早期版本的 Windows 兼容。
DEFAULT_PALETTE 默认调色板。此调色板由系统调色板中的 20 种静态颜色组成。

返回值

如果函数成功，则指向被替换的 CGdiObject 对象的指针。实际指向的对象是 CPen、CBrush 或 CFont 对象。如果调用失败，则返回值为 NULL。

`CDC::SetAbortProc`

安装打印作业的中止过程。

int SetAbortProc(BOOL (CALLBACK* lpfn)(HDC, int));

参数

lpfn
指向作为中止过程安装的中止函数的指针。有关回调函数的详细信息，请参阅 CDC::SetAbortProc 的回调函数。

返回值

指定 SetAbortProc 函数的结果。以下一些值比其他值更有可能，但所有值都是可能的。

SP_ERROR 常规错误。
SP_OUTOFDISK 当前没有足够的磁盘空间可用于后台处理，并且没有更多可用空间。
SP_OUTOFMEMORY 没有足够的内存可用于后台处理。
SP_USERABORT 用户通过打印管理器结束了作业。

备注

如果应用程序允许在后台处理期间取消打印作业，则必须在使用 StartDoc 成员函数启动打印作业之前设置中止函数。打印管理器在后台处理期间调用中止函数，以允许应用程序取消打印作业或处理磁盘空间不足的情况。如果未设置中止函数，则在没有足够的磁盘空间进行后台处理的情况下，打印作业将失败。

Microsoft Visual C++ 的功能简化了传递给 SetAbortProc 的回调函数的创建。传递给 EnumObjects 成员函数的地址是指向使用 __declspec(dllexport) 和 __stdcall 调用约定导出的函数的指针。

也不必在应用程序的模块定义文件的 EXPORTS 语句中导出函数名称。可以改为使用 EXPORT 函数修饰符，如

BOOL CALLBACK EXPORT AFunction( HDC, int );

回调注册接口现在是类型安全的（必须传入一个函数指针，该指针指向特定回调的正确函数类型）。

所有回调函数必须在返回到 Windows 之前捕获 Microsoft Foundation 异常，因为无法跨回调边界引发异常。有关异常的详细信息，请参阅异常一文。

`CDC::SetArcDirection`

设置要用于弧线和矩形函数的绘图方向。

int SetArcDirection(int nArcDirection);

参数

nArcDirection
指定新的弧线方向。此参数可以是以下值之一：

AD_COUNTERCLOCKWISE 逆时针方向绘制的图形。
AD_CLOCKWISE 顺时针方向绘制的图形。

返回值

如果成功，则指定旧的弧线方向；否则为 0。

备注

默认方向为逆时针方向。 SetArcDirection 函数指定以下函数的绘制方向：

Arc	饼图
`ArcTo`	`Rectangle`
`Chord`	`RoundRect`
`Ellipse`

`CDC::SetAttribDC`

调用此函数以设置属性设备上下文 m_hAttribDC。

virtual void SetAttribDC(HDC hDC);

参数

hDC
Windows 设备上下文。

备注

此成员函数不会将设备上下文附加到 CDC 对象。仅将输出设备上下文附加到 CDC 对象。

`CDC::SetBkColor`

将当前背景色设置为指定颜色。

virtual COLORREF SetBkColor(COLORREF crColor);

参数

crColor
指定新背景色。

返回值

以前的背景色作为 RGB 颜色值。如果发生错误，则返回值为 0x80000000。

备注

如果设备无法显示指定的颜色，系统会将背景色设置为最接近的物理颜色。

`CDC::SetBkMode`

设置背景模式。

int SetBkMode(int nBkMode);

参数

nBkMode
指定要设置的模式。此参数可以是以下值之一：

OPAQUE 在绘制文本、阴影画笔或触笔之前，使用当前背景色填充背景。这是默认后台模式。
TRANSPARENT 背景在绘制之前没有改变。

返回值

先前的背景模式。

注解

背景模式定义系统是否在绘制文本、阴影画笔或任何非实线的触笔样式之前删除绘图图面上的现有背景色。

示例

请参阅 CWnd::OnCtlColor 的示例。

`CDC::SetBoundsRect`

控制指定设备上下文的边框信息的累积。

UINT SetBoundsRect(
    LPCRECT lpRectBounds,
    UINT flags);

参数

lpRectBounds
指向用于设置边框的 RECT 结构或 CRect 对象。矩形维度以逻辑坐标提供。此参数可以为 NULL。

flags
指定新矩形如何与累积的矩形组合。此参数可为以下值的组合：

DCB_ACCUMULATE 将 lpRectBounds 指定的矩形添加到边框（使用矩形联合操作）。
DCB_DISABLE 关闭边界累积。
DCB_ENABLE 打开边界累积。（边界累积的默认设置是禁用的。）

返回值

如果函数成功，则为边框的当前状态。与 flags 一样，返回值可以是 DCB_ 值的组合：

DCB_ACCUMULATE 边框不为空。此值将始终设置。
DCB_DISABLE 边界累积已关闭。
DCB_ENABLE 边界累积已开启。

备注

Windows 可以保留所有绘图操作的边框。应用程序可以查询和重置此矩形。绘图边界可用于使位图缓存失效。

`CDC::SetBrushOrg`

指定 GDI 将分配给应用程序选择到设备上下文中的下一个画笔的原点。

CPoint SetBrushOrg(
    int x,
    int y);

CPoint SetBrushOrg(POINT point);

参数

x
指定新原点的 x 坐标（以设备单元表示）。该值必须在 0-7 范围内。

y
指定新原点的 y 坐标（以设备单元表示）。该值必须在 0-7 范围内。

point
指定新原点的 x 坐标和 y 坐标。每个值必须在 0-7 范围内。可以为此参数传递 POINT 结构或 CPoint 对象。

返回值

画笔的上一个原点（以设备单元表示）。

注解

画笔原点的默认坐标为 (0,0)。若要更改画笔的原点，请为 CBrush 对象调用 UnrealizeObject 函数，调用 SetBrushOrg，然后调用 SelectObject 成员函数以将画笔选择到设备上下文中。

不要将 SetBrushOrg 与常用的 CBrush 对象一起使用。

`CDC::SetColorAdjustment`

使用指定值设置设备上下文的颜色调整值。

BOOL SetColorAdjustment(const COLORADJUSTMENT* lpColorAdjust);

参数

lpColorAdjust
指向包含颜色调整值的 COLORADJUSTMENT 数据结构。

返回值

如果成功，则不为 0；否则为 0。

备注

颜色调整值用于调整源位图的输入颜色，以便在设置 HALFTONE 模式时调用 CDC::StretchBlt 成员函数。

`CDC::SetDCBrushColor`

将当前设备上下文 (DC) 画笔颜色设置为指定的颜色值。

COLORREF SetDCBrushColor(COLORREF crColor);

参数

crColor
指定新的画笔颜色。

返回值

如果函数成功，则返回值将先前的 DC 画笔颜色指定为 COLORREF 值。

如果函数失败，则返回值为 CLR_INVALID。

注解

此方法模拟 SetDCBrushColor 函数的功能，如 Windows SDK 中所述。

`CDC::SetDCPenColor`

将当前设备上下文 (DC) 触笔颜色设置为指定的颜色值。

COLORREF SetDCPenColor(COLORREF crColor);

参数

crColor
指定新的触笔颜色。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

此成员函数使用 Win32 函数 SetDCPenColor，如 Windows SDK 中所述。

`CDC::SetGraphicsMode`

设置指定设备上下文的图形模式。

int SetGraphicsMode(int iMode);

参数

iMode
指定图形模式。有关此参数可以采用的值的列表，请参阅 SetGraphicsMode。

返回值

成功时返回旧图形模式。

失败时返回 0。若要获得扩展的错误信息，请调用 GetLastError。

注解

此方法包装 Windows GDI 函数 SetGraphicsMode。

`CDC::SetLayout`

调用此成员函数可将设备上下文的文本和图形布局更改为从右到左，即阿拉伯语和希伯来语等区域性的标准布局。

DWORD SetLayout(DWORD dwLayout);

参数

dwLayout
设备上下文布局和位图控件标志。它可以是以下值的组合。

值	含义
`LAYOUT_BITMAPORIENTATIONPRESERVED`	禁用对 `CDC::BitBlt` 和 `CDC::StretchBlt` 的调用的任何反射。
`LAYOUT_RTL`	将默认水平布局设置为从右到左。
`LAYOUT_LTR`	将默认布局设置为从左到右。

返回值

如果成功，则为设备上下文的上一布局。

如果失败，则为 GDI_ERROR。若要获得扩展的错误信息，请调用 GetLastError。

备注

通常，你不会为窗口调用 SetLayout。相反，可以通过设置扩展窗口样式（例如 WS_EX_RTLREADING）来控制窗口中从右到左的布局。设备上下文（如打印机或图元文件）不会继承此布局。为从右到左布局设置设备上下文的唯一方法是调用 SetLayout。

如果调用 SetLayout(LAYOUT_RTL)，SetLayout 会自动将映射模式更改为 MM_ISOTROPIC。因此，对 GetMapMode 的后续调用将返回 MM_ISOTROPIC，而不是 MM_TEXT。

在某些情况下，例如对于许多位图，可能希望保留从左到右的布局。在这些情况下，通过调用 BitBlt 或 StretchBlt 呈现图像，然后将 dwLayout 的位图控件标志设置为 LAYOUT_BITMAPORIENTATIONPRESERVED。

使用 LAYOUT_RTL 标志更改布局后，通常指定右或左的标志会反转。为避免混淆，可能需要为标准标志定义替代名称。有关建议的备用标志名称的列表，请参阅 Windows SDK 中的 SetLayout。

`CDC::SetMapMode`

设置映射模式。

virtual int SetMapMode(int nMapMode);

参数

nMapMode
指定新映射模式。可以是以下任一值：

MM_ANISOTROPIC 逻辑单元转换为具有任意缩放轴的任意单元。将映射模式设置为 MM_ANISOTROPIC 不会更改当前窗口或视区设置。若要更改单元、方向和缩放比例，请调用 SetWindowExt 和 SetViewportExt 成员函数。
MM_HIENGLISH 每个逻辑单元转换为 0.001 英寸。正 x 向右；正 y 向上。
MM_HIMETRIC 每个逻辑单元转换为 0.01 毫米。正 x 向右；正 y 向上。
MM_ISOTROPIC 逻辑单元转换为具有同样缩放轴的任意单元；也就是说，沿 x 轴的 1 个单元等于沿 y 轴的 1 个单元。使用 SetWindowExt 和 SetViewportExt 成员函数指定所需的单元和轴的方向。 GDI 会根据需要进行调整以确保 x 和 y 单元的大小保持不变。
MM_LOENGLISH 每个逻辑单元转换为 0.01 英寸。正 x 向右；正 y 向上。
MM_LOMETRIC 每个逻辑单元转换为 0.1 毫米。正 x 向右；正 y 向上。
MM_TEXT 每个逻辑单元转换为 1 个设备像素。正 x 向右；正 y 向下。
MM_TWIPS 每个逻辑单元转换为点的 1/20。（因为一个点是 1/72 英寸，一个缇是 1/1440 英寸。）正 x 向右；正 y 向上。

返回值

先前的映射模式。

备注

映射模式定义用于将逻辑单元转换为设备单元的度量单位；它还定义了设备的 x 轴和 y 轴的方向。 GDI 使用映射模式将逻辑坐标转换为相应的设备坐标。 MM_TEXT 模式允许应用程序以设备像素工作，其中 1 个单元等于 1 个像素。像素的物理大小因设备而异。

MM_HIENGLISH、MM_HIMETRIC、MM_LOENGLISH、MM_LOMETRIC 和 MM_TWIPS 模式对于必须以物理上有意义的单位（例如英寸或毫米）绘制的应用程序很有用。 MM_ISOTROPIC 模式可确保 1:1 的纵横比，这在务必保留图像的精确形状时非常有用。 MM_ANISOTROPIC 模式允许独立调整 x 坐标和 y 坐标。

注意

如果调用 SetLayout 将 DC（设备上下文）更改为从右到左的布局，SetLayout 会自动将映射模式更改为 MM_ISOTROPIC。

示例

请参阅 CView::OnPrepareDC 的示例。

`CDC::SetMapperFlags`

更改字体映射器在将逻辑字体转换为物理字体时使用的方法。

DWORD SetMapperFlags(DWORD dwFlag);

参数

dwFlag
指定字体映射器是否尝试将字体的纵横高度和宽度与设备匹配。当此值为 ASPECT_FILTERING 时，映射器仅选择 x 朝向和 y 朝向与指定设备的字体完全匹配的字体。

返回值

字体映射器标志的上一个值。

备注

应用程序可以使用 SetMapperFlags 使字体映射器尝试仅选择与指定设备的纵横比完全匹配的物理字体。

仅使用光栅字体的应用程序可以使用 SetMapperFlags 函数来确保字体映射器选择的字体在指定设备上具有吸引力和可读性。使用可缩放 (TrueType) 字体的应用程序通常不使用 SetMapperFlags。

如果没有物理字体的纵横比与逻辑字体中的规范相匹配，GDI 将选择一个新的纵横比并选择一种与此新纵横比相匹配的字体。

`CDC::SetMiterLimit`

设置设备上下文的斜角连接长度限制。

BOOL SetMiterLimit(float fMiterLimit);

参数

fMiterLimit
指定设备上下文的新斜接限制。

返回值

如果该函数成功，则为非 0；否则为 0。

注解

斜接长度定义为从联接内侧的线墙的交点到联接外侧的线墙的交点的距离。斜接限制是斜接长度与线宽的最大允许比率。默认斜接限制为 10.0。

`CDC::SetOutputDC`

调用此成员函数，以设置输出设备上下文 m_hDC。

virtual void SetOutputDC(HDC hDC);

参数

hDC
Windows 设备上下文。

注解

仅当设备上下文未附加到 CDC 对象时，才能调用此成员函数。此成员函数设置 m_hDC，但不将设备上下文附加到 CDC 对象。

`CDC::SetPixel`

将指定点处的像素设置为 crColor 指定颜色的最接近近似值。

COLORREF SetPixel(
    int x,
    int y,
    COLORREF crColor);

COLORREF SetPixel(
    POINT point,
    COLORREF crColor);

参数

x
指定要设置的点的逻辑 x 坐标。

y
指定要设置的点的逻辑 y 坐标。

crColor
一个 COLORREF RGB 值，指定用于绘制点的颜色。有关此值的说明，请参阅 Windows SDK 中的 COLORREF。

point
指定要设置的点的逻辑 x 坐标和 y 坐标。可以为此参数传递 POINT 结构或 CPoint 对象。

返回值

绘制点的颜色的 RGB 数值。如果使用该颜色的近似值，则此值可能与 crColor 指定的值不同。如果函数失败（如果该点在剪切区域之外），则返回值为 -1。

注解

该点必须位于剪切区域中。如果该点不在剪切区域中，则该函数不执行任何操作。

不是所有的设备都支持 SetPixel 函数。若要确定设备是否支持 SetPixel，请使用 RASTERCAPS 索引调用 GetDeviceCaps 成员函数并检查 RC_BITBLT 标志的返回值。

`CDC::SetPixelV`

将指定坐标处的像素设置为最接近指定颜色的值。

BOOL SetPixelV(
    int x,
    int y,
    COLORREF crColor);

BOOL SetPixelV(
    POINT point,
    COLORREF crColor);

参数

x
指定要设置的点的 x 坐标（以逻辑单元表示）。

y
指定要设置的点的 y 坐标（以逻辑单元表示）。

crColor
指定要用于绘制点的颜色。

point
指定要设置的点的逻辑 x 坐标和 y 坐标。可以为此参数传递 POINT 数据结构或 CPoint 对象。

返回值

如果该函数成功，则为非 0；否则为 0。

注解

该点必须同时位于剪切区域和设备图面的可见部分。并非所有设备都支持该成员函数。有关详细信息，请参阅 CDC::GetDeviceCaps 成员函数中的 RC_BITBLT 功能。 SetPixelV 比 SetPixel 快，因为它不需要返回绘制的点的颜色值。

`CDC::SetPolyFillMode`

设置多边形填充模式。

int SetPolyFillMode(int nPolyFillMode);

参数

nPolyFillMode
指定新的填充模式。此值可以是 ALTERNATE 或 WINDING。 Windows 中设置的默认模式为 ALTERNATE。

返回值

如果成功，则为上一个填充模式；否则为 0。

备注

当多边形填充模式为 ALTERNATE 时，系统会在每个扫描行上填充奇数多边形和偶数多边形边之间的区域。也就是说，系统会填充第一条边和第二条边之间的区域、第三条边和第四条边之间的区域，以此类推。这是默认模式。

当多边形填充模式为 WINDING 时，系统使用绘制图形的方向来确定是否填充区域。多边形中的每条线段都按顺时针或逆时针方向绘制。每当从闭合区域绘制到图形外部的虚线通过顺时针线段时，计数就会递增。当此虚线通过逆时针线段时，计数将递减。如果此虚线达到图形外部时计数为非零，则会填充区域。

`CDC::SetROP2`

设置当前绘图模式。

int SetROP2(int nDrawMode);

参数

nDrawMode
指定新的绘图模式。可以是以下任一值：

R2_BLACK 像素始终为黑色。
R2_WHITE 像素始终为白色。
R2_NOP 像素保持不变。
R2_NOT 像素是屏幕颜色的反转。
R2_COPYPEN 像素是触笔颜色。
R2_NOTCOPYPEN 像素是触笔颜色的反转。
R2_MERGEPENNOT 像素是触笔颜色和屏幕颜色反转的组合（最终像素 = (~ 屏幕像素) | 触笔）。
R2_MASKPENNOT 像素是触笔和屏幕反转共有的颜色的组合（最终像素 = (~ 屏幕像素) & 触笔）。
R2_MERGENOTPEN 像素是屏幕颜色和触笔颜色反转的组合（最终像素 = (~ 触笔) | 屏幕像素）。
R2_MASKNOTPEN 像素是屏幕和触笔反转共有的颜色的组合（最终像素 = (~ 触笔) & 屏幕像素）。
R2_MERGEPEN 像素是触笔颜色和屏幕颜色的组合（最终像素 = 触笔 | 屏幕像素）。
R2_NOTMERGEPEN 像素是 R2_MERGEPEN 颜色的反转（最终像素 = ~ (触笔 | 屏幕像素)）。
R2_MASKPEN 像素是触笔和屏幕共有的颜色的组合（最终像素 = 触笔 & 屏幕像素）。
R2_NOTMASKPEN 像素是 R2_MASKPEN 颜色的反转（最终像素 = ~ (触笔 & 屏幕像素)）。
R2_XORPEN 像素是触笔或屏幕中颜色的组合，但不是两者（最终像素 = 触笔 ^ 屏幕像素）。
R2_NOTXORPEN 像素是 R2_XORPEN 颜色的反转（最终像素 = ~ (触笔 ^ 屏幕像素)）。

返回值

先前的绘图模式。

它可以是 Windows SDK 中提供的任何值。

备注

绘图模式指定触笔的颜色和填充对象的内部如何与显示图面上已有的颜色组合。

绘图模式仅适用于光栅设备；它不适用于向量设备。绘图模式是二进制光栅运算代码，表示两个变量的所有可能的布尔组合，使用二进制运算符 &、| 和 ^（不包括 |）和一元运算 ~。

`CDC::SetStretchBltMode`

设置 StretchBlt 成员函数的位图拉伸模式。

int SetStretchBltMode(int nStretchMode);

参数

nStretchMode
指定拉伸模式。可以是以下任一值：

值	说明
`BLACKONWHITE`	使用已消除像素和现有像素的颜色值执行布尔 `&` 运算。如果位图是单色位图，则此模式会以牺牲白色像素为代价保留黑色像素。
`COLORONCOLOR`	删除像素。此模式会删除所有已消除的像素线，而不会尝试保留其信息。
`HALFTONE`	将源矩形中的像素映射到目标矩形中的像素块。目标像素块上的平均颜色近似于源像素的颜色。
	设置 `HALFTONE` 拉伸模式后，应用程序必须调用 Win32 函数 `SetBrushOrgEx` 来设置画笔原点。如果无法执行此操作，则会发生画笔未对齐。
`STRETCH_ANDSCANS`	Windows 95/98：与 `BLACKONWHITE` 相同
`STRETCH_DELETESCANS`	Windows 95/98：与 `COLORONCOLOR` 相同
`STRETCH_HALFTONE`	Windows 95/98：与 `HALFTONE` 相同。
`STRETCH_ORSCANS`	Windows 95/98：与 `WHITEONBLACK` 相同
`WHITEONBLACK`	使用已消除像素和现有像素的颜色值执行布尔 `\|` 运算。如果位图是单色位图，则此模式会以牺牲黑色像素为代价保留白色像素。

返回值

先前的拉伸模式。可以是 STRETCH_ANDSCANS、STRETCH_DELETESCANS 或 STRETCH_ORSCANS。

注解

位图拉伸模式定义如何从使用该函数压缩的位图中删除信息。

BLACKONWHITE(STRETCH_ANDSCANS) 和 WHITEONBLACK(STRETCH_ORSCANS) 模式通常用于保留单色位图中的前景像素。 The COLORONCOLOR(STRETCH_DELETESCANS) 模式通常用于保留彩色位图中的颜色。

HALFTONE 模式比其他三种模式需要更多的源图像处理；它比其他模式慢，但会产生更高质量的图像。此外，必须在设置 HALFTONE 模式后调用 SetBrushOrgEx 以避免画笔不对齐。

根据设备驱动程序的功能，其他拉伸模式也可能可用。

`CDC::SetTextAlign`

设置文本对齐标志。

UINT SetTextAlign(UINT nFlags);

参数

nFlags
指定文本对齐标志。标志指定点与限定文本的矩形之间的关系。该点可以是当前位置，也可以是文本输出函数指定的坐标。限定文本的矩形由文本字符串中的相邻字符单元格定义。 nFlags 参数可以是以下三个类别中的一个或多个标志。从每个类别中只选择一个标志。第一个类别影响 x 方向的文本对齐方式：

TA_CENTER 将点与边框的水平中心对齐。
TA_LEFT 将点与边框的左侧对齐。这是默认设置。
TA_RIGHT 将点与边框的右侧对齐。

第二个类别影响 y 方向的文本对齐方式：

TA_BASELINE 将点与所选字体的基线对齐。
TA_BOTTOM 将点与边框的底部对齐。
TA_TOP 将点与边框的顶部对齐。这是默认设置。

第三个类别确定在写入文本时是否更新当前位置：

TA_NOUPDATECP 每次调用文本输出函数后不更新当前位置。这是默认设置。
TA_UPDATECP 每次调用文本输出函数后更新当前 x 位置。新位置位于文本边框的右侧。设置此标志时，将忽略调用 TextOut 成员函数中指定的坐标。

返回值

如果成功，则为上一个文本对齐设置。低位字节包含水平设置，高位字节包含垂直设置；否则为 0。

备注

TextOut 和 ExtTextOut 成员函数在显示器或设备上定位文本字符串时使用这些标志。标志特定指定点与限定文本的矩形之间的关系。此点的坐标作为参数传递给 TextOut 成员函数。限定文本的矩形由文本字符串中的相邻字符单元格形成。

`CDC::SetTextCharacterExtra`

设置字符间距量。

int SetTextCharacterExtra(int nCharExtra);

参数

nCharExtra
指定要添加到每个字符的额外空间量（以逻辑单元表示）。如果当前映射模式不是 MM_TEXT，则 nCharExtra 会被转换并四舍五入到最近的像素。

返回值

先前字符间的间距量。

备注

当 GDI 将一行文本写入设备上下文时，它会将此间距添加到每个字符（包括中断字符）。字符间的间距量的默认值为 0。

`CDC::SetTextColor`

将文本颜色设置为指定颜色。

virtual COLORREF SetTextColor(COLORREF crColor);

参数

crColor
将文本的颜色指定为 RGB 颜色值。

返回值

上一个文本颜色的 RGB 值。

注解

当将文本写入此设备上下文以及在彩色和单色设备上下文之间转换位图时，系统将使用此文本颜色。

如果设备无法表示指定的颜色，系统会将文本颜色设置为最接近的物理颜色。字符的背景色由 SetBkColor 和 SetBkMode 成员函数指定。

示例

请参阅 CWnd::OnCtlColor 的示例。

`CDC::SetTextJustification`

向字符串中的中断字符添加空格。

int SetTextJustification(
    int nBreakExtra,
    int nBreakCount);

参数

nBreakExtra
指定要添加到文本行的总额外空间（以逻辑单元表示）。如果当前映射模式不是 MM_TEXT，则将此参数给定的值转换为当前映射模式并四舍五入到最近的设备单元。

nBreakCount
指定行中的中断字符数。

返回值

如果该函数成功，则为 1；否则为 0。

备注

应用程序可以使用 GetTextMetrics 成员函数来检索字体的中断字符。

调用 SetTextJustification 成员函数后，对文本输出函数（如 TextOut）的调用将指定的额外空间均匀分布到指定的中断字符数之间。中断字符通常是空格字符 (ASCII 32)，但也可以由字体定义为其他字符。

成员函数 GetTextExtent 通常与 SetTextJustification 一起使用。 GetTextExtent 在对齐之前计算给定线条的宽度。应用程序可以通过从对齐后的字符串宽度中减去 GetTextExtent 返回的值来确定在 nBreakExtra 参数中指定的空间量。

SetTextJustification 函数可用于对齐包含不同字体的多个运行的行。在这种情况下，必须通过单独对齐和编写每个运行来分段创建行。

由于在对齐期间可能会出现舍入误差，因此系统会保留定义当前误差的运行误差项。对齐包含多个运行的行时，GetTextExtent 在计算下一次运行的范围时会自动使用此误差项。这允许文本输出函数将误差混合到新的运行中。

每行对齐后，必须清除此误差项以防止将其合并到下一行中。可以通过将 nBreakExtra 设置为 0 调用 SetTextJustification 来清除该项。

`CDC::SetViewportExt`

设置设备上下文视区的 x 范围和 y 范围。

virtual CSize SetViewportExt(
    int cx,
    int cy);

CSize SetViewportExt(SIZE size);

参数

cx
指定视区的 x 范围（以设备单元表示）。

cy
指定视区的 y 范围（以设备单元表示）。

size
指定视区的 x 范围和 y 范围（以设备单元表示）。

返回值

作为 CSize 对象的先前视区范围。发生错误时，返回的 CSize 对象的 x 坐标和 y 坐标都设置为 0。

注解

视区和设备上下文窗口一起定义 GDI 如何将逻辑坐标系中的点映射到实际设备坐标系中的点。换句话说，它们定义 GDI 如何将逻辑坐标转换为设备坐标。

设置以下映射模式时，将忽略对 SetWindowExt 和 SetViewportExt 的调用：

`MM_HIENGLISH`	`MM_LOMETRIC`
`MM_HIMETRIC`	`MM_TEXT`
`MM_LOENGLISH`	`MM_TWIPS`

设置 MM_ISOTROPIC 模式后，应用程序必须在调用 SetViewportExt 之前调用 SetWindowExt 成员函数。

示例

请参阅 CView::OnPrepareDC 的示例。

`CDC::SetViewportOrg`

设置设备上下文的视区原点。

virtual CPoint SetViewportOrg(
    int x,
    int y);

CPoint SetViewportOrg(POINT point);

参数

x
指定视区原点的 x 坐标（以设备单元表示）。该值必须位于设备坐标系的范围内。

y
指定视区原点的 y 坐标（以设备单元表示）。该值必须位于设备坐标系的范围内。

point
指定视区的原点。这些值必须位于设备坐标系的范围内。可以为此参数传递 POINT 结构或 CPoint 对象。

返回值

作为 CPoint 对象的先前视区原点（以设备坐标表示）。

备注

视区和设备上下文窗口一起定义 GDI 如何将逻辑坐标系中的点映射到实际设备坐标系中的点。换句话说，它们定义 GDI 如何将逻辑坐标转换为设备坐标。

视区原点标记设备坐标系中 GDI 将窗口原点映射到的点，该点是 SetWindowOrg 成员函数指定的逻辑坐标系中的一个点。 GDI 通过遵循将窗口原点映射到视区原点所需的相同过程来映射所有其他点。例如，围绕窗口原点的圆中的所有点都将位于围绕视区原点的圆中。同样，通过窗口原点的线条中的所有点都将位于通过视区原点的线条中。

示例

请参阅 CView::OnPrepareDC 的示例。

`CDC::SetWindowExt`

设置与设备上下文关联的窗口的 x 范围和 y 范围。

virtual CSize SetWindowExt(
    int cx,
    int cy);

CSize SetWindowExt(SIZE size);

参数

cx
指定窗口的 x 范围（以逻辑单元表示）。

cy
指定窗口的 y 范围（以逻辑单元表示）。

size
指定窗口的 x 范围和 y 范围（以逻辑单元表示）。

返回值

作为 CSize 对象的先前窗口范围（以逻辑单元表示）。如果发生错误，返回的 CSize 对象的 x 坐标和 y 坐标都设置为 0。

备注

窗口和设备上下文视区一起定义 GDI 如何将逻辑坐标系中的点映射到设备坐标系中的点。

设置以下映射模式时，将忽略对 SetWindowExt 和 SetViewportExt 函数的调用：

MM_HIENGLISH
MM_HIMETRIC
MM_LOENGLISH
MM_LOMETRIC
MM_TEXT
MM_TWIPS

设置 MM_ISOTROPIC 模式后，应用程序必须在调用 SetViewportExt 之前调用 SetWindowExt 成员函数。

示例

请参阅 CView::OnPrepareDC 的示例。

`CDC::SetWindowOrg`

设置设备上下文的窗口原点。

CPoint SetWindowOrg(
    int x,
    int y);

CPoint SetWindowOrg(POINT point);

参数

x
指定窗口的新源点的逻辑 x 坐标。

y
指定窗口的新源点的逻辑 y 坐标。

point
指定窗口的新源点的逻辑坐标。可以为此参数传递 POINT 结构或 CPoint 对象。

返回值

作为 CPoint 对象的先前窗口原点。

备注

窗口和设备上下文视区一起定义 GDI 如何将逻辑坐标系中的点映射到设备坐标系中的点。

窗口原点标记逻辑坐标系中 GDI 将视区原点映射到的点，该点是 SetWindowOrg 函数指定的设备坐标系中的一个点。 GDI 通过遵循将窗口原点映射到视区原点所需的相同过程来映射所有其他点。例如，围绕窗口原点的圆中的所有点都将位于围绕视区原点的圆中。同样，通过窗口原点的线条中的所有点都将位于通过视区原点的线条中。

`CDC::SetWorldTransform`

为指定的设备上下文设置世界空间和页面空间之间的二维线性转换。此转换可用于缩放、旋转、扭曲或转换图形输出。

BOOL SetWorldTransform(const XFORM& rXform);

参数

rXform
对包含转换数据的 XFORM 结构的引用。

返回值

成功时返回一个非零值。

失败时返回 0。

若要获得扩展的错误信息，请调用 GetLastError。

备注

此方法包装 Windows GDI 函数 SetWorldTransform。

`CDC::StartDoc`

通知设备驱动程序一个新的打印作业正在启动，并且所有后续的 StartPage 和 EndPage 调用都应在同一个作业下进行后台处理，直到发生 EndDoc 调用。

int StartDoc(LPDOCINFO lpDocInfo);
int StartDoc(LPCTSTR lpszDocName);

参数

lpDocInfo
指向包含文档文件名和输出文件名的 DOCINFO 结构。

lpszDocName
指向包含文档文件名的字符串的指针。

返回值

如果函数成功，则返回值大于 0。此值是文档的打印作业标识符。

如果函数失败，则返回值小于或等于 0。

注解

这可确保超过一页的文档不会与其他作业穿插。

对于 Windows 版本 3.1 及更高版本，此函数将替换 STARTDOC 打印机转义。使用此函数可确保包含多于一页的文档不会与其他打印作业穿插。

StartDoc 不应在图元文件内使用。

示例

此代码片段获取默认打印机，打开打印作业，并在后台处理一个含有“Hello, World!”的页面。由于此代码打印的文本未缩放到打印机的逻辑单元，因此输出文本可能采用非常小的字母，以至于结果不可读。 CDC 缩放函数（例如 SetMapMode、SetViewportOrg 和 SetWindowExt）可用于修复缩放。

void CDCView::DoStartDoc()
{
   // get the default printer
   CPrintDialog dlg(FALSE);
   dlg.GetDefaults();

   // is a default printer set up?
   HDC hdcPrinter = dlg.GetPrinterDC();
   if (hdcPrinter == NULL)
   {
      MessageBox(_T("Buy a printer!"));
   }
   else
   {
      // create a CDC and attach it to the default printer
      CDC dcPrinter;
      dcPrinter.Attach(hdcPrinter);

      // call StartDoc() to begin printing
      DOCINFO docinfo;
      memset(&docinfo, 0, sizeof(docinfo));
      docinfo.cbSize = sizeof(docinfo);
      docinfo.lpszDocName = _T("CDC::StartDoc() Code Fragment");

      // if it fails, complain and exit gracefully
      if (dcPrinter.StartDoc(&docinfo) < 0)
      {
         MessageBox(_T("Printer wouldn't initialize"));
      }
      else
      {
         // start a page
         if (dcPrinter.StartPage() < 0)
         {
            MessageBox(_T("Could not start page"));
            dcPrinter.AbortDoc();
         }
         else
         {
            // actually do some printing
            CGdiObject *pOldFont = dcPrinter.SelectStockObject(SYSTEM_FONT);

            dcPrinter.TextOut(50, 50, _T("Hello World!"), 12);

            dcPrinter.EndPage();
            dcPrinter.EndDoc();
            dcPrinter.SelectObject(pOldFont);
         }
      }
   }
}

`CDC::StartPage`

调用此成员函数，以使打印机驱动程序做好接收数据的准备。

int StartPage();

返回值

如果函数成功，则大于或等于 0，如果发生错误，则为负值。

备注

StartPage 取代 NEWFRAME 和 BANDINFO 转义。

有关打印调用序列的概述，请参阅 StartDoc 成员函数。

系统在调用 StartPage 和 EndPage 之间禁用 ResetDC 成员函数。

示例

请参阅 CDC::StartDoc 的示例。

`CDC::StretchBlt`

将位图从源矩形复制到目标矩形，必要时可拉伸或压缩位图以符合目标矩形的尺寸。

BOOL StretchBlt(
    int x,
    int y,
    int nWidth,
    int nHeight,
    CDC* pSrcDC,
    int xSrc,
    int ySrc,
    int nSrcWidth,
    int nSrcHeight,
    DWORD dwRop);

参数

x
指定目标矩形左上角的 x 坐标（使用逻辑单位）。

y
指定目标矩形左上角的 y 坐标（使用逻辑单位）。

nWidth
指定目标矩形的宽度（使用逻辑单位）。

nHeight
指定目标矩形的高度（使用逻辑单位）。

pSrcDC
指定源设备上下文。

xSrc
指定源矩形左上角的 x 坐标（使用逻辑单位）。

ySrc
指定源矩形左上角的 y 坐标（使用逻辑单位）。

nSrcWidth
指定源矩形的宽度（使用逻辑单位）。

nSrcHeight
指定源矩形的高度（使用逻辑单位）。

dwRop
指定要执行的光栅操作。光栅操作代码定义 GDI 如何合并涉及当前画笔、可能的源位图和目标位图的输出操作中的颜色。该参数可能是下列值之一：

BLACKNESS 将所有输出变为黑色。
DSTINVERT 反转目标位图。
MERGECOPY 使用布尔 AND 运算符组合图案和源位图。
MERGEPAINT 使用布尔 OR 运算符将反转的源位图与目标位图组合。
NOTSRCCOPY 将反转的源位图复制到目标。
NOTSRCERASE 反转使用布尔 OR 运算符组合目标位图和源位图的结果。
PATCOPY 将图案复制到目标位图。
PATINVERT 使用布尔 XOR 运算符将目标位图与图案组合。
PATPAINT 使用布尔 OR 运算符将反转的源位图与图案组合。使用布尔 OR 运算符将此运算的结果与目标位图组合。
SRCAND 使用布尔 AND 运算符组合目标位图和源位图的像素。
SRCCOPY 将源位图复制到目标位图。
SRCERASE 反转目标位图并使用布尔 AND 运算符将结果与源位图组合。
SRCINVERT 使用布尔 XOR 运算符组合目标位图和源位图的像素。
SRCPAINT 使用布尔 OR 运算符组合目标位图和源位图的像素。
WHITENESS 将所有输出变为白色。

返回值

如果绘制出位图，则为非 0；否则为 0。

备注

该函数使用目标设备上下文的拉伸模式（由 SetStretchBltMode 设置）确定如何拉伸或压缩位图。

StretchBlt 函数将 pSrcDC 给定的源设备中的位图移动到目标设备，该设备使用成员函数即将被调用的设备上下文对象表示。 xSrc、ySrc、nSrcWidth 和 nSrcHeight 参数定义源矩形的左上角和尺寸。 x、y、nWidth 和 nHeight 参数提供目标矩形的左上角和尺寸。 dwRop 指定的光栅操作定义源位图和目标设备上已存在的位如何合并。

如果 nSrcWidth 与 nWidth 或 nSrcHeight 与 nHeight 参数的符号不同，则 StretchBlt 函数将创建位图的镜像。如果 nSrcWidth 与 nWidth 符号不同，则该函数将沿 x 轴创建位图的镜像。如果 nSrcHeight 与 nHeight 符号不同，则该函数将沿 y 轴创建位图的镜像。

StretchBlt 函数将在内存中拉伸或压缩源位图，然后将结果复制到目标。如果一个模式将与该结果合并，则合并操作会等到拉伸的源位图复制到目标后执行。如果使用画笔，则为在目标设备上下文中选择的画笔。目标坐标将根据目标设备上下文进行转换；源坐标将根据源设备上下文进行转换。

如果目标位图、源位图和模式位图没有相同的颜色格式，StretchBlt 将转换源位图和模式位图，以与目标位图匹配。在转换中将使用目标设备上下文的前景色和背景色。

如果 StretchBlt 必须将单色位图转换为彩色，则会将白色位 (1) 设置为背景色，黑色位 (0) 设置为前景色。若要将彩色位图转换为单色，它会将与背景色匹配的像素设置为白色 (1)，其他所有像素设置为黑色 (0)。在转换中将使用彩色设备上下文的前景色和背景色。

不是所有的设备都支持 StretchBlt 函数。若要确定设备是否支持 StretchBlt，请使用 RASTERCAPS 索引调用 GetDeviceCaps 成员函数并检查 RC_STRETCHBLT 标志的返回值。

`CDC::StrokeAndFillPath`

闭合路径中所有开放的图形，使用当前触笔绘制路径轮廓，并使用当前画笔填充路径内部。

BOOL StrokeAndFillPath();

返回值

如果该函数成功，则为非 0；否则为 0。

注解

设备上下文必须包含封闭的路径。 StrokeAndFillPath 成员函数与闭合路径中所有打开的图形、分别对路径进行描边和填充的效果相同，只是即使触笔很宽，填充区域也不会与描边区域重叠。

`CDC::StrokePath`

使用当前触笔呈现指定的路径。

BOOL StrokePath();

返回值

如果该函数成功，则为非 0；否则为 0。

备注

设备上下文必须包含封闭的路径。

`CDC::TabbedTextOut`

调用此成员函数，以在指定位置写入字符串，将制表符扩展到制表位位置数组中指定的值。

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);

参数

x
指定字符串起点的逻辑 x 坐标。

y
指定字符串起点的逻辑 y 坐标。

lpszString
指向要绘制的字符串。可以为此参数传递指向字符数组的指针或 CString 对象。

nCount
指定 lpszString 指向的字符串的长度。

nTabPositions
指定制表位位置数组中的值的数量。

lpnTabStopPositions
指向包含制表位位置的数组（以逻辑单元表示）。制表位必须按升序排列；最小的 x 值应该是数组中的第一项。

nTabOrigin
指定扩展制表符的起始位置的 x 坐标（以逻辑单元表示）。

str
包含指定字符的 CString 对象。

返回值

作为 CSize 对象的字符串的尺寸（以逻辑单元表示）。

注解

文本是用当前所选字体编写的。如果 nTabPositions 为 0 且 lpnTabStopPositions 为 NULL，则制表符将扩展为平均字符宽度的八倍。

如果 nTabPositions 为 1，则制表位将按由 lpnTabStopPositions 数组中的第一个值指定的距离分隔。如果 lpnTabStopPositions 数组包含多个值，则为数组中的每个值设置一个制表位，最多为 nTabPositions 指定的数字。 nTabOrigin 参数允许应用程序为一行多次调用 TabbedTextOut 函数。如果应用程序多次调用该函数并且每次都将 nTabOrigin 设置为相同的值，则该函数将扩展所有相对于 nTabOrigin 指定位置的制表符。

默认情况下，函数既不使用也不更新当前位置。如果应用程序在调用该函数时需要更新当前位置，则应用程序可以调用 SetTextAlign 成员函数，并将 nFlags 设置为 TA_UPDATECP。设置此标志后，Windows 将在随后的 TabbedTextOut 调用中忽略 x 和 y 参数，而是使用当前位置。

`CDC::TextOut`

使用当前选定的字体在指定位置写入字符串。

virtual BOOL TextOut(
    int x,
    int y,
    LPCTSTR lpszString,
    int nCount);

BOOL TextOut(
    int x,
    int y,
    const CString& str);

参数

x
指定文本起点的逻辑 x 坐标。

y
指定文本起点的逻辑 y 坐标。

lpszString
指向要绘制的字符串。

nCount
指定字符串中的字符数。

str
包含要绘制的字符的 CString 对象。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

字符原点位于字符单元格的左上角。默认情况下，函数既不使用也不更新当前位置。

如果应用程序在调用 TextOut 时需要更新当前位置，则应用程序可以调用 SetTextAlign 成员函数，并将 nFlags 设置为 TA_UPDATECP。设置此标志后，Windows 将在随后的 TextOut 调用中忽略 x 和 y 参数，而是使用当前位置。

示例

请参阅 CDC::BeginPath 的示例。

`CDC::TransparentBlt`

调用此成员函数将颜色数据的位块（对应于来自指定源设备上下文的像素矩形）传输到目标设备上下文。

BOOL TransparentBlt(
    int xDest,
    int yDest,
    int nDestWidth,
    int nDestHeight,
    CDC* pSrcDC,
    int xSrc,
    int ySrc,
    int nSrcWidth,
    int nSrcHeight,
    UINT clrTransparent);

参数

xDest
指定目标矩形左上角的 x 坐标（以逻辑单元表示）。

yDest
指定目标矩形左上角的 y 坐标（以逻辑单元表示）。

nDestWidth
指定目标矩形的宽度（以逻辑单元表示）。

nDestHeight
指定目标矩形的高度（以逻辑单元表示）。

pSrcDC
指向源设备上下文的指针。

xSrc
指定源矩形的 x 坐标（以逻辑单元表示）。

ySrc
指定源矩形的 y 坐标（以逻辑单元表示）。

nSrcWidth
指定源矩形的宽度（以逻辑单元表示）。

nSrcHeight
指定源矩形的高度（以逻辑单元表示）。

clrTransparent
要视为透明的源位图中的 RGB 颜色。

返回值

如果成功，则返回 TRUE；否则返回 FALSE。

备注

TransparentBlt 允许透明度；即，clrTransparent 指示的 RGB 颜色对传输呈现透明。

有关详细信息，请参阅 Windows SDK 中的 TransparentBlt。

`CDC::UpdateColors`

通过将工作区中每一个像数的当前颜色与系统调色板匹配来更新设备上下文的工作区。

void UpdateColors();

备注

当系统调色板发生更改时，具有已实现逻辑调色板的非活动窗口可以调用 UpdateColors 作为重新绘制其工作区的替代方法。

有关使用调色板的详细信息，请参阅 Windows SDK 中的 UpdateColors。

UpdateColors 成员函数通常比重绘区域更快地更新工作区。但是，由于该函数在系统调色板更改之前根据每个像素的颜色执行颜色转换，因此每次调用此函数都会导致一些颜色准确性的损失。

`CDC::WidenPath`

将当前路径重新定义为：使用当前选择的触笔在设备上下文中描绘路径时将绘制的区域。

BOOL WidenPath();

返回值

如果该函数成功，则为非 0；否则为 0。

注解

仅当当前触笔是由 CreatePen 成员函数的第二个版本创建的几何触笔，或者如果触笔是使用 CreatePen 的第一个版本创建的且宽度（以设备单元表示）大于 1 时，此函数才成功。设备上下文必须包含封闭的路径。路径中的任何贝塞尔曲线都将转换为近似于加宽曲线的直线序列。因此，调用 WidenPath 后，路径中不会保留贝塞尔曲线。

另请参阅

CObject 类
 层次结构图
 CPaintDC 类
 CWindowDC 类
 CClientDC 类
 CMetaFileDC 类

CDC 类

语法

成员

公共构造函数

公共方法

公共运算符

公共数据成员

备注

继承层次结构

要求

CDC::AbortDoc

返回值

备注

示例

CDC::AbortPath

返回值

备注

CDC::AddMetaFileComment

参数

返回值

注解

CDC::AlphaBlend

参数

返回值

备注

CDC::AngleArc

参数

返回值

注解

CDC::Arc

参数

返回值

备注

示例

CDC::ArcTo

参数

返回值

注解

CDC::Attach

参数

返回值

注解

CDC::BeginPath

返回值

备注

示例

CDC::BitBlt

参数

返回值

备注

示例

CDC::CDC

CDC::Chord

参数

返回值

备注

示例

CDC::CloseFigure

返回值

备注

CDC::CreateCompatibleDC

参数

返回值

备注

示例

CDC::CreateDC

参数

返回值

备注

CDC::CreateIC

参数

返回值

备注

CDC::DeleteDC

返回值

备注

示例

CDC::DeleteTempMap

CDC::Detach

返回值

`CDC` 类

`CDC::AbortDoc`

`CDC::AbortPath`

`CDC::AddMetaFileComment`

`CDC::AlphaBlend`

`CDC::AngleArc`

`CDC::Arc`

`CDC::ArcTo`

`CDC::Attach`

`CDC::BeginPath`

`CDC::BitBlt`

`CDC::CDC`

`CDC::Chord`

`CDC::CloseFigure`

`CDC::CreateCompatibleDC`

`CDC::CreateDC`

`CDC::CreateIC`

`CDC::DeleteDC`

`CDC::DeleteTempMap`

`CDC::Detach`

`CDC::DPtoHIMETRIC`

`CDC::DPtoLP`

`CDC::Draw3dRect`

`CDC::DrawDragRect`

`CDC::DrawEdge`

`CDC::DrawEscape`

`CDC::DrawFocusRect`

`CDC::DrawFrameControl`

`CDC::DrawIcon`

`CDC::DrawState`

`CDC::DrawText`

`CDC::DrawTextEx`

`CDC::Ellipse`

`CDC::EndDoc`

`CDC::EndPage`

`CDC::EndPath`

`CDC::EnumObjects`

`CDC::Escape`

`CDC::ExcludeClipRect`