ScrollConsoleScreenBuffer 函式

發行項
12/13/2023

重要

本文件說明已不再是生態系統藍圖一部分的控制台平臺功能。我們不建議您在新產品中使用此內容，但我們將繼續支持無限期的未來現有使用量。我們慣用的新式解決方案著重於 虛擬終端機序列 ，以在跨平臺案例中達到最大相容性。您可以在傳統 主控台與虛擬終端機 檔中找到此設計決策的詳細資訊。

移動螢幕緩衝區中的數據區塊。移動的效果可以藉由指定裁剪矩形來限制，因此裁剪矩形外的控制台畫面緩衝區內容不會變更。

語法

BOOL WINAPI ScrollConsoleScreenBuffer(
  _In_           HANDLE     hConsoleOutput,
  _In_     const SMALL_RECT *lpScrollRectangle,
  _In_opt_ const SMALL_RECT *lpClipRectangle,
  _In_           COORD      dwDestinationOrigin,
  _In_     const CHAR_INFO  *lpFill
);

參數

hConsoleOutput [in]
主控台螢幕緩衝區的控點。句柄必須具有 GENERIC_READ 訪問許可權。如需詳細資訊，請參閱主控台緩衝區安全性和存取權限。

lpScrollRectangle [in]
SMALL_RECT 結構的指標，其成員指定要移動之控制台畫面緩衝區矩形的左上方和右下角座標。

lpClipRectangle [in， optional]
SMALL_RECT 結構的指標，其成員指定受捲動影響之控制台畫面緩衝區矩形的左上方和右下角座標。此指標可以是 NULL。

dwDestinationOrigin [in]
COORD 結構，以字元指定 lpScrollRectangle 內容之新位置的左上角。

lpFill [in]
CHAR_INFO 結構的指標，指定要用來填滿 lpScrollRectangle 和 lpClipRectangle 交集內單元格的字元和色彩屬性，因為移動而留下空白。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

ScrollConsoleScreenBuffer 會將 lpScrollRectangle 參數所指定之螢幕緩衝區矩形區域的內容複製到控制台畫面緩衝區的另一個區域。目標矩形具有與 lpScrollRectangle 矩形相同的維度，其左上角位於 dwDestinationOrigin 參數所指定的座標。未與目標矩形重疊的 lpScrollRectangle 這些部分會填入 lpFill 參數所指定的字元和色彩屬性。

裁剪矩形會套用至 lpScrollRectangle 矩形和目標矩形中所做的變更。例如，如果裁剪矩形不包含已由 lpFill 內容填滿的區域，則區域的原始內容會保持不變。

如果卷動或目標區域超出控制台畫面緩衝區的維度，則會裁剪它們。例如，如果 lpScrollRectangle 是（0,0）和（19,19）和 dwDestinationOrigin 所包含的區域（10,15），則目標矩形是（10,15）和（29,34）所包含的區域。不過，如果控制台畫面緩衝區寬 50 個字元且高 30 個字元，則目標矩形會裁剪為（10,15）和（29,29,29）。如果參數指定SMALL_RECT結構，也會根據 lpClipRectangle 裁剪控制台畫面緩衝區的變更。如果裁剪矩形指定為（0,0）和（49,19），則只會變更控制台畫面緩衝區的該區域。

此函式會從主控台的目前字碼頁使用 Unicode 字元或 8 位元字元。主控台的字碼頁一開始會預設為系統的 OEM 字碼頁。若要變更控制台的字碼頁，請使用 SetConsoleCP 或 SetConsoleOutputCP 函式。舊版取用者也可以使用 chcp 或 mode con cp select= 命令，但不建議用於新的開發。

提示

不建議使用此 API，而且沒有 虛擬終端機 對等專案。您可以使用卷動邊界來修正畫面區域、游標定位來設定區域外的使用中位置，以及強制文字移動的新行。您可以移動游標、 設定圖形屬性，以及撰寫一般文字，以填滿剩餘的空間。

範例

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

需求


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