SetConsoleWindowInfo 函式

發行項
12/13/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。

備註

如果指定的視窗矩形超出控制台畫面緩衝區的界限，函式就會失敗。這表示如果 bAbsolute 為 FALSE，則 lpConsoleWindow 矩形的 Top 和 Left 成員（或計算的頂端和左座標）不能小於零。同樣地， Bottom 和 Right 成員（或計算的下角和右座標）不能分別大於（螢幕緩衝區高度 – 1）和（螢幕緩衝區寬度 – 1）。如果 Right 成員（或導出的右座標）小於或等於左成員（或計算的左座標），或者 Bottom 成員（或導出的下角座標）小於或等於 Top 成員（或計算的頂端座標），則函式也會失敗。

對於具有多個螢幕緩衝區的控制台，變更一個螢幕緩衝區的視窗位置不會影響其他螢幕緩衝區的視窗位置。

若要判斷螢幕緩衝區視窗的目前大小和位置，請使用 GetConsoleScreenBufferInfo 函式。此函式也會傳回視窗的大小上限，指定目前的螢幕緩衝區大小、目前的字型大小和螢幕大小。 GetLargestConsoleWindowSize 函式會傳回目前字型和螢幕大小上限，但不會考慮控制台畫面緩衝區的大小。

SetConsoleWindowInfo 可用來捲動控制台畫面緩衝區的內容，方法是移動視窗矩形的位置，而不變更其大小。

提示

不建議使用此 API，而且沒有 虛擬終端機 對等專案。此決策會刻意將 Windows 平臺與其他操作系統一致，而該操作系統會授與使用者對此簡報選項的完整控制權。透過跨平臺公用程式和 SSH 之類的傳輸進行遠端處理的應用程式在使用這個 API 時可能無法如預期般運作。

範例

如需範例，請參閱卷動螢幕緩衝區的視窗。

需求


最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
頁首	ConsoleApi2.h （透過 WinCon.h，包含 Windows.h）
程式庫	Kernel32.lib
DLL	Kernel32.dll