Fungsi WriteConsoleOutput

Artikel
12/13/2023

Penting

Dokumen ini menjelaskan fungsionalitas platform konsol yang tidak lagi menjadi bagian dari peta jalan ekosistem kami. Kami tidak menyarankan penggunaan konten ini dalam produk baru, tetapi kami akan terus mendukung penggunaan yang ada untuk masa depan yang tidak terbatas. Solusi modern pilihan kami berfokus pada urutan terminal virtual untuk kompatibilitas maksimum dalam skenario lintas platform. Anda dapat menemukan informasi selengkapnya tentang keputusan desain ini di konsol klasik vs. dokumen terminal virtual kami.

Menulis data atribut karakter dan warna ke blok persegi panjang tertentu dari sel karakter dalam buffer layar konsol. Data yang akan ditulis diambil dari blok persegi panjang berukuran sesuai pada lokasi tertentu di buffer sumber.

Sintaks

BOOL WINAPI WriteConsoleOutput(
  _In_          HANDLE      hConsoleOutput,
  _In_    const CHAR_INFO   *lpBuffer,
  _In_          COORD       dwBufferSize,
  _In_          COORD       dwBufferCoord,
  _Inout_       PSMALL_RECT lpWriteRegion
);

Parameter

hConsoleOutput [in]
Handel ke buffer layar konsol. Handel harus memiliki akses GENERIC_WRITE yang tepat. Untuk informasi selengkapnya, lihat Keamanan dan Hak Akses Buffer Konsol.

lpBuffer [in]
Data yang akan ditulis ke buffer layar konsol. Pointer ini diperlakukan sebagai asal array dua dimensi struktur CHAR_INFO yang ukurannya ditentukan oleh parameter dwBufferSize .

dwBufferSize [in]
Ukuran buffer yang diacu oleh parameter lpBuffer , dalam sel karakter. Anggota X dari struktur COORD adalah jumlah kolom; anggota Y adalah jumlah baris.

dwBufferCoord [in]
Koordinat sel kiri atas di buffer yang diarahkan oleh parameter lpBuffer . Anggota X dari struktur COORD adalah kolom , dan anggota Y adalah baris .

lpWriteRegion [masuk, keluar]
Penunjuk ke struktur SMALL_RECT. Pada input, anggota struktur menentukan koordinat kiri atas dan kanan bawah persegi panjang buffer layar konsol untuk ditulis. Pada output, anggota struktur menentukan persegi panjang aktual yang digunakan.

Nilai hasil

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

WriteConsoleOutput memperlakukan buffer sumber dan buffer layar tujuan sebagai array dua dimensi (kolom dan baris sel karakter). Persegi panjang yang diarahkan oleh parameter lpWriteRegion menentukan ukuran dan lokasi blok yang akan ditulis di buffer layar konsol. Persegi panjang dengan ukuran yang sama terletak dengan sel kiri atasnya pada koordinat parameter dwBufferCoord dalam array lpBuffer . Data dari sel yang berada di persimpangan persegi panjang ini dan persegi panjang buffer sumber (yang dimensinya ditentukan oleh parameter dwBufferSize ) ditulis ke persegi panjang tujuan.

Sel dalam persegi panjang tujuan yang lokasi sumbernya sesuai berada di luar batas persegi panjang buffer sumber dibiarkan tidak terpengaruh oleh operasi tulis. Dengan kata lain, ini adalah sel yang tidak ada data yang tersedia untuk ditulis.

Sebelum WriteConsoleOutput kembali, WriteConsoleOutput mengatur anggota lpWriteRegion ke persegi panjang buffer layar aktual yang terpengaruh oleh operasi tulis. Persegi panjang ini mencerminkan sel dalam persegi panjang tujuan yang ada sel yang sesuai di buffer sumber, karena WriteConsoleOutput mengklip dimensi persegi panjang tujuan ke batas buffer layar konsol.

Jika persegi panjang yang ditentukan oleh lpWriteRegion sepenuhnya berada di luar batas buffer layar konsol, atau jika persegi panjang yang sesuai diposisikan sepenuhnya di luar batas buffer sumber, tidak ada data yang ditulis. Dalam hal ini, fungsi kembali dengan anggota struktur yang ditujukkan oleh parameter lpWriteRegion yang diatur sehingga anggota Kanan kurang dari Kiri, atau anggota Bawah kurang dari Atas. Untuk menentukan ukuran buffer layar konsol, gunakan fungsi GetConsoleScreenBufferInfo.

WriteConsoleOutput tidak berpengaruh pada posisi kursor.

Fungsi ini menggunakan karakter Unicode atau karakter 8-bit dari halaman kode konsol saat ini. Halaman kode konsol default awalnya ke halaman kode OEM sistem. Untuk mengubah halaman kode konsol, gunakan fungsi SetConsoleCP atau SetConsoleOutputCP. Konsumen warisan juga dapat menggunakan perintah chcp atau mode con cp select= , tetapi tidak disarankan untuk pengembangan baru.

Tip

API ini memiliki terminal virtual yang setara dalam urutan pemformatan teks dan pemosisian kursor. Pindahkan kursor ke lokasi untuk menyisipkan, menerapkan pemformatan yang diinginkan, dan menulis teks. Urutan terminal virtual direkomendasikan untuk semua pengembangan baru dan yang sedang berlangsung.

Contoh

Misalnya, lihat Membaca dan Menulis Blok Karakter dan Atribut.

Persyaratan


Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Header	ConsoleApi2.h (melalui WinCon.h, termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll
Nama Unicode dan ANSI	WriteConsoleOutputW (Unicode) dan WriteConsoleOutputA (ANSI)

Bagikan melalui