SetConsoleWindowInfo 函数

项目
10/30/2023

重要

本文档介绍控制台平台功能，该功能已不再是生态系统蓝图的一部分。我们不建议在新产品中使用此内容，但我们未来将无限期支持现有使用。我们的首选最新解决方案侧重于虚拟终端序列，以实现跨平台方案中的最大兼容性。有关此设计决策的详细信息，请参阅经典控制台与虚拟终端文档。

设置控制台屏幕缓冲区窗口的当前大小和位置。

语法

BOOL WINAPI SetConsoleWindowInfo(
  _In_       HANDLE     hConsoleOutput,
  _In_       BOOL       bAbsolute,
  _In_ const SMALL_RECT *lpConsoleWindow
);

参数

hConsoleOutput [in]
控制台屏幕缓冲区的句柄。该句柄必须具有 GENERIC_READ 访问权限。有关详细信息，请参阅控制台缓冲区安全性和访问权限。

bAbsolute [in]
如果此参数为 TRUE，则坐标为窗口指定新的左上角和右下角。如果为 FALSE，则坐标相对于当前窗口角的坐标。

lpConsoleWindow [in]
指向 SMALL_RECT 结构的指针，该结构为窗口指定新的左上角和右下角。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

注解

如果指定的窗口矩形超出控制台屏幕缓冲区的边界，则函数失败。这意味着，lpConsoleWindow 矩形的 Top 和 Left 成员（如果 bAbsolute 为 FALSE 则为计算出的上坐标和左坐标）不能小于零。同样，Bottom 和 Right 成员（或计算出的下坐标和右坐标）分别不能大于（屏幕缓冲区高度 – 1）和（屏幕缓冲区宽度 – 1）。如果 Right 成员（或计算出的右坐标）小于或等于 Left 成员（或计算出的左坐标），或者 Bottom 成员（或计算出的下坐标）小于或等于 Top 成员（或计算出的上坐标），该函数也会失败。

对于具有多个屏幕缓冲区的控制台，更改一个屏幕缓冲区的窗口位置不会影响其他屏幕缓冲区的窗口位置。

若要确定屏幕缓冲区的当前大小和位置，请使用 GetConsoleScreenBufferInfo 函数。此函数还返回窗口的大小最大值，给定当前屏幕缓冲区大小、当前字号和屏幕大小。 GetLargestConsoleWindowSize 函数可返回最大窗口大小，给定当前字号和屏幕大小，但是不考虑控制台窗口缓冲区的大小。

SetConsoleWindowInfo 可用于通过移动窗口矩形的位置而不更改其大小，来滚动控制台屏幕缓冲区的内容。

提示

不建议使用此 API，并且此 API 没有虚拟终端等效项。此决策有意使 Windows 平台与其他操作系统保持一致，在这些操作系统中，用户可以完全控制此演示选项。如果使用此 API，则通过跨平台实用工具和传输（例如 SSH）进行远程处理的应用程序可能无法正常工作。

示例

如需示例，请参阅滚动屏幕缓冲区的窗口。

要求


最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
Header	ConsoleApi2.h (via WinCon.h, include Windows.h)
库	Kernel32.lib
DLL	Kernel32.dll