Fungsi DrawText (winuser.h)

Artikel
03/04/2024

Fungsi DrawText menggambar teks yang diformat dalam persegi panjang yang ditentukan. Ini memformat teks sesuai dengan metode yang ditentukan (memperluas tab, membenarkan karakter, garis putus, dan sebagainya).

Untuk menentukan opsi pemformatan tambahan, gunakan fungsi DrawTextEx .

Sintaks

int DrawText(
  [in]      HDC     hdc,
  [in, out] LPCTSTR lpchText,
  [in]      int     cchText,
  [in, out] LPRECT  lprc,
  [in]      UINT    format
);

Parameter

[in] hdc

Handel ke konteks perangkat.

[in, out] lpchText

Penunjuk ke string yang menentukan teks yang akan digambar. Jika parameter nCount adalah -1, string harus dihentikan null.

Jika uFormat menyertakan DT_MODIFYSTRING, fungsi dapat menambahkan hingga empat karakter tambahan ke string ini. Buffer yang berisi string harus cukup besar untuk mengakomodasi karakter tambahan ini.

[in] cchText

Panjang, dalam karakter, dari string. Jika nCount adalah -1, maka parameter lpchText diasumsikan sebagai penunjuk ke string yang dihentikan null dan DrawText menghitung jumlah karakter secara otomatis.

[in, out] lprc

Penunjuk ke struktur RECT yang berisi persegi panjang (dalam koordinat logis) tempat teks akan diformat.

[in] format

Metode pemformatan teks. Parameter ini bisa menjadi satu atau beberapa nilai berikut.

Nilai	Makna
DT_BOTTOM	Membenarkan teks ke bagian bawah persegi. Nilai ini hanya digunakan dengan nilai DT_SINGLELINE.
DT_CALCRECT	Menentukan lebar dan tinggi persegi panjang. Jika ada beberapa baris teks, DrawText menggunakan lebar persegi panjang yang diacu oleh parameter lpRect dan memperluas dasar persegi panjang untuk mengikat baris terakhir teks. Jika kata terbesar lebih lebar dari persegi panjang, lebar diperluas. Jika teks kurang dari lebar persegi, lebarnya akan berkurang. Jika hanya ada satu baris teks, DrawText memodifikasi sisi kanan persegi panjang sehingga mengikat karakter terakhir dalam baris. Dalam kedua kasus, DrawText mengembalikan tinggi teks yang diformat tetapi tidak menggambar teks.
DT_CENTER	Tengahkan teks secara horizontal dalam persegi panjang.
DT_EDITCONTROL	Menduplikasi karakteristik tampilan teks dari kontrol edit multibaris. Secara khusus, lebar karakter rata-rata dihitung dengan cara yang sama seperti untuk kontrol edit, dan fungsi tidak menampilkan baris terakhir yang terlihat sebagian.
DT_END_ELLIPSIS	Untuk teks yang ditampilkan, jika akhir string tidak pas di persegi panjang, maka akan terpotok dan elipsis ditambahkan. Jika kata yang tidak berada di akhir string melampaui batas persegi panjang, kata tersebut dipotok tanpa elipsis. String tidak dimodifikasi kecuali bendera DT_MODIFYSTRING ditentukan. Bandingkan dengan DT_PATH_ELLIPSIS dan DT_WORD_ELLIPSIS.
DT_EXPANDTABS	Memperluas karakter tab. Jumlah karakter default per tab adalah delapan. Nilai DT_WORD_ELLIPSIS, DT_PATH_ELLIPSIS, dan DT_END_ELLIPSIS tidak dapat digunakan dengan nilai DT_EXPANDTABS.
DT_EXTERNALLEADING	Menyertakan font eksternal di depan dalam tinggi garis. Biasanya, di depan eksternal tidak disertakan dalam tinggi baris teks.
DT_HIDEPREFIX	Mengabaikan karakter awalan ampersand (&) dalam teks. Huruf berikut tidak akan digarisbawahi, tetapi karakter awalan mnemonik lainnya masih diproses. Contoh: string input: "A&bc&&d" normal: "Abc&d" DT_HIDEPREFIX: "Abc&d" Bandingkan dengan DT_NOPREFIX dan DT_PREFIXONLY.
DT_INTERNAL	Menggunakan font sistem untuk menghitung metrik teks.
DT_LEFT	Meratakan teks ke kiri.
DT_MODIFYSTRING	Memodifikasi string yang ditentukan agar sesuai dengan teks yang ditampilkan. Nilai ini tidak berpengaruh kecuali DT_END_ELLIPSIS atau DT_PATH_ELLIPSIS ditentukan.
DT_NOCLIP	Gambar tanpa kliping. DrawText agak lebih cepat ketika DT_NOCLIP digunakan.
DT_NOFULLWIDTHCHARBREAK	Mencegah pemisah baris pada DBCS (string karakter lebar ganda), sehingga aturan pemecahan baris setara dengan string SBCS. Misalnya, ini dapat digunakan di jendela Korea, untuk lebih banyak keterbacaan label ikon. Nilai ini tidak berpengaruh kecuali DT_WORDBREAK ditentukan.
DT_NOPREFIX	Menonaktifkan pemrosesan karakter awalan. Biasanya, DrawText menafsirkan karakter awalan mnemonic & sebagai direktif untuk menggarisbawahi karakter berikut, dan karakter awalan mnemonik && sebagai direktif untuk mencetak satu &. Dengan menentukan DT_NOPREFIX, pemrosesan ini dinonaktifkan. Misalnya, Contoh: string input: "A&bc&&d" normal: "Abc&d" DT_NOPREFIX: "A&bc&&d" Bandingkan dengan DT_HIDEPREFIX dan DT_PREFIXONLY.
DT_PATH_ELLIPSIS	Untuk teks yang ditampilkan, mengganti karakter di tengah string dengan elipsis sehingga hasilnya pas dalam persegi panjang yang ditentukan. Jika string berisi karakter garis miring terbalik (\\), DT_PATH_ELLIPSIS mempertahankan sebanyak mungkin teks setelah garis miring terbalik terakhir. String tidak dimodifikasi kecuali bendera DT_MODIFYSTRING ditentukan. Bandingkan dengan DT_END_ELLIPSIS dan DT_WORD_ELLIPSIS.
DT_PREFIXONLY	Hanya menggambar garis bawah pada posisi karakter setelah karakter awalan ampersand (&). Tidak menggambar karakter lain dalam string. Misalnya, Contoh: string input: "A&bc&&d"n normal: "Abc&d" DT_PREFIXONLY: " _ " Bandingkan dengan DT_HIDEPREFIX dan DT_NOPREFIX.
DT_RIGHT	Meratakan teks ke kanan.
DT_RTLREADING	Tata letak dalam urutan baca kanan-ke-kiri untuk teks dua arah ketika font yang dipilih ke hdc adalah font Ibrani atau Arab. Urutan baca default untuk semua teks adalah kiri-ke-kanan.
DT_SINGLELINE	Menampilkan teks pada satu baris saja. Pengembalian pengangkutan dan umpan baris tidak merusak garis.
DT_TABSTOP	Mengatur perhentian tab. Bit 15-8 (byte urutan tinggi dari kata berurutan rendah) dari parameter uFormat menentukan jumlah karakter untuk setiap tab. Jumlah karakter default per tab adalah delapan. Nilai DT_CALCRECT, DT_EXTERNALLEADING, DT_INTERNAL, DT_NOCLIP, dan DT_NOPREFIX tidak dapat digunakan dengan nilai DT_TABSTOP.
DT_TOP	Membenarkan teks ke bagian atas persegi.
DT_VCENTER	Tengahkan teks secara vertikal. Nilai ini hanya digunakan dengan nilai DT_SINGLELINE.
DT_WORDBREAK	Memecah kata-kata. Garis secara otomatis rusak di antara kata jika kata akan meluas melewati tepi persegi panjang yang ditentukan oleh parameter lpRect . Urutan umpan jalur kembali pengangkutan juga merusak garis. Jika ini tidak ditentukan, output berada di satu baris.
DT_WORD_ELLIPSIS	Memotong kata apa pun yang tidak pas di persegi panjang dan menambahkan elipsis. Bandingkan dengan DT_END_ELLIPSIS dan DT_PATH_ELLIPSIS.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah tinggi teks dalam unit logis. Jika DT_VCENTER atau DT_BOTTOM ditentukan, nilai yang dikembalikan adalah offset dari lpRect->top ke bagian bawah teks yang digambar.

Jika fungsi gagal, nilai yang dikembalikan adalah nol.

Keterangan

Fungsi DrawText menggunakan font, warna teks, dan warna latar belakang konteks perangkat untuk menggambar teks. Kecuali format DT_NOCLIP digunakan, DrawText mengklip teks sehingga tidak muncul di luar persegi panjang yang ditentukan. Perhatikan bahwa teks dengan pertumpukan yang signifikan dapat dipotong, misalnya, "W" awal dalam string teks atau teks yang dalam miring. Semua pemformatan diasumsikan memiliki beberapa baris kecuali format DT_SINGLELINE ditentukan.

Jika font yang dipilih terlalu besar untuk persegi panjang yang ditentukan, fungsi DrawText tidak mencoba untuk mengganti font yang lebih kecil.

Mode perataan teks untuk konteks perangkat harus menyertakan bendera TA_LEFT, TA_TOP, dan TA_NOUPDATECP.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	winuser.h (sertakan Windows.h)
Pustaka	User32.lib
DLL	User32.dll
Set API	ext-ms-win-ntuser-misc-l1-1-0 (diperkenalkan dalam Windows 8)