WriteConsoleOutput関数
重要
このドキュメントでは、エコシステム ロードマップの一部ではなくなったコンソール プラットフォームの機能について説明します。 このコンテンツを新しい製品で使用することはお勧めしませんが、今後も既存の使用をサポートし続けます。 推奨される最新のソリューションでは、クロスプラットフォーム シナリオでの互換性を最大限に高める仮想ターミナル シーケンスに重点を置いています。 この設計決定の詳細については、クラシック コンソールと仮想ターミナルのドキュメントを参照してください。
コンソール画面バッファー内の指定した四角形の文字セル ブロックに、文字属性データと色属性データを書き込みます。 書き込まれるデータは、ソース バッファー内の指定した位置にある、対応するサイズの四角形ブロックから取得されます。
構文
BOOL WINAPI WriteConsoleOutput(
_In_ HANDLE hConsoleOutput,
_In_ const CHAR_INFO *lpBuffer,
_In_ COORD dwBufferSize,
_In_ COORD dwBufferCoord,
_Inout_ PSMALL_RECT lpWriteRegion
);
パラメーター
hConsoleOutput [in]
コンソール画面バッファーのハンドル。 ハンドルには、GENERIC_WRITE アクセス権が必要です。 詳細については、「コンソール バッファーのセキュリティとアクセス権」を参照してください。
lpBuffer [in]
コンソール画面バッファに書き込まれるデータ。 このポインターは、dwBufferSize パラメーターでサイズが指定CHAR_INFO構造体の 2 次元配列の原点として扱われます。
dwBufferSize [in]
lpBuffer パラメーターが指すバッファーのサイズ (文字セル単位)。 COORD 構造体の X メンバーは列数です。Y メンバーは行数です。
dwBufferCoord [in]
lpBuffer パラメーターが指すバッファー内の左上のセルの座標。 COORD 構造体の X メンバーは列であり、Y メンバーは行です。
lpWriteRegion [in, out]
SMALL_RECT構造体へのポインター。 入力時に、構造体メンバーは、書き込むコンソール画面バッファーの四角形の左上と右下の座標を指定します。 出力時に、構造体メンバーは使用された実際の四角形を指定します。
戻り値
関数が成功すると、戻り値は 0 以外になります。
関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
WriteConsoleOutput は、ソース バッファーとコピー先画面バッファーを 2 次元配列 (文字セルの列と行) として扱います。 lpWriteRegion パラメーターが指す四角形は、コンソール画面バッファーに書き込まれるブロックのサイズと場所を指定します。 同じサイズの四角形は、lpBuffer 配列の dwBufferCoord パラメーターの座標にある左上のセルと共に配置されます。 この四角形とソース バッファーの四角形 (dwBufferSize パラメーターで指定された次元) の積集合にあるセルのデータが、コピー先の四角形に書き込まれます。
ソース バッファーの四角形の境界外にある、対応するソース位置を持つ移動先の四角形内のセルは、書き込み操作の影響を受けません。 つまり、データを書き込むことができないセルです。
WriteConsoleOutput が戻る前に、lpWriteRegion のメンバーを、書き込み操作の影響を受ける実際の画面バッファーの四角形に設定します。 WriteConsoleOutput はコピー先の四角形のサイズをコンソール画面バッファーの境界にクリップするため、この四角形は、ソース バッファー内に対応するセルが存在していた移動先の四角形内のセルを反映します。
lpWriteRegion で指定された四角形がコンソール画面バッファーの境界の外側にある場合、または対応する四角形がソース バッファーの境界の外に完全に配置されている場合、データは書き込まれなくなります。 この場合、関数は、Right メンバーが Left より小さいか、Bottom メンバーが Top より小さいよう、lpWriteRegion パラメーター セットが指す構造体のメンバーを返します。 コンソール画面バッファのサイズを確認するには、GetConsoleScreenBufferInfo 関数を使用します。
WriteConsoleOutput はカーソル位置に影響しません。
この関数では、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 名 | WriteConsoleOutputW (Unicode) と WriteConsoleOutputA (ANSI) |