Fungsi ExtTextOutA (wingdi.h)

Artikel
03/08/2023

Fungsi ExtTextOut menggambar teks menggunakan font, warna latar belakang, dan warna teks yang saat ini dipilih. Anda dapat secara opsional menyediakan dimensi yang akan digunakan untuk kliping, opaquing, atau keduanya.

Sintaks

BOOL ExtTextOutA(
  [in] HDC        hdc,
  [in] int        x,
  [in] int        y,
  [in] UINT       options,
  [in] const RECT *lprect,
  [in] LPCSTR     lpString,
  [in] UINT       c,
  [in] const INT  *lpDx
);

Parameter

[in] hdc

Handel ke konteks perangkat.

[in] x

Koordinat x, dalam koordinat logis, dari titik referensi yang digunakan untuk memosisikan string.

[in] y

Koordinat y, dalam koordinat logis, dari titik referensi yang digunakan untuk memosisikan string.

[in] options

Menentukan cara menggunakan persegi panjang yang ditentukan aplikasi. Parameter ini bisa menjadi satu atau beberapa nilai berikut.

Nilai	Makna
ETO_CLIPPED	Teks akan dipotong ke persegi panjang.
ETO_GLYPH_INDEX	Array lpString mengacu pada array yang dikembalikan dari GetCharacterPlacement dan harus diurai langsung oleh GDI karena tidak diperlukan pemrosesan khusus bahasa lebih lanjut. Pengindeksan Glyph hanya berlaku untuk font TrueType, tetapi bendera dapat digunakan untuk font bitmap dan vektor untuk menunjukkan bahwa tidak ada pemrosesan bahasa lebih lanjut yang diperlukan dan GDI harus memproses string secara langsung. Perhatikan bahwa semua indeks glyph adalah nilai 16-bit meskipun string diasumsikan sebagai array nilai 8-bit untuk font raster. Untuk ExtTextOutW, indeks glyph disimpan ke metafile. Namun, untuk menampilkan karakter yang benar, metafile harus diputar kembali menggunakan font yang sama. Untuk ExtTextOutA, indeks glyph tidak disimpan.
ETO_IGNORELANGUAGE	Dicadangkan untuk penggunaan sistem. Jika aplikasi menetapkan bendera ini, aplikasi kehilangan dukungan pembuatan skrip internasional dan dalam beberapa kasus mungkin tidak menampilkan teks.
ETO_NUMERICSLATIN	Untuk menampilkan angka, gunakan digit Eropa.
ETO_NUMERICSLOCAL	Untuk menampilkan angka, gunakan digit yang sesuai dengan lokal.
ETO_OPAQUE	Warna latar belakang saat ini harus digunakan untuk mengisi persegi.
ETO_PDY	Ketika ini diatur, array yang ditujukkan oleh lpDx berisi pasangan nilai. Nilai pertama dari setiap pasangan adalah, seperti biasa, jarak antara asal sel karakter yang berdekatan, tetapi nilai kedua adalah perpindahan di sepanjang arah vertikal font.
ETO_RTLREADING	Windows edisi bahasa Timur Tengah: Jika nilai ini ditentukan dan font Ibrani atau Arab dipilih ke dalam konteks perangkat, string adalah output menggunakan urutan baca kanan-ke-kiri. Jika nilai ini tidak ditentukan, string adalah output dalam urutan kiri-ke-kanan. Efek yang sama dapat dicapai dengan mengatur nilai TA_RTLREADING di SetTextAlign. Nilai ini dipertahankan untuk kompatibilitas mundur.

Nilai ETO_GLYPH_INDEX dan ETO_RTLREADING tidak dapat digunakan bersamaan. Karena ETO_GLYPH_INDEX menyiratkan bahwa semua pemrosesan bahasa telah selesai, fungsi mengabaikan bendera ETO_RTLREADING jika juga ditentukan.

[in] lprect

Penunjuk ke struktur RECT opsional yang menentukan dimensi, dalam koordinat logis, persegi panjang yang digunakan untuk kliping, opaquing, atau keduanya.

[in] lpString

Penunjuk ke string yang menentukan teks yang akan digambar. String tidak perlu dihentikan nol, karena cbCount menentukan panjang string.

[in] c

Panjang string yang ditujukan ke oleh lpString.

Nilai ini mungkin tidak melebihi 8192.

[in] lpDx

Penunjuk ke array nilai opsional yang menunjukkan jarak antara asal sel karakter yang berdekatan. Misalnya, unit logis lpDx[i] memisahkan asal sel karakter i dan sel karakter i + 1.

Mengembalikan nilai

Jika string digambar, nilai yang dikembalikan bukan nol. Namun, jika versi ANSI extTextOut dipanggil dengan ETO_GLYPH_INDEX, fungsi mengembalikan TRUE meskipun fungsi tidak melakukan apa-apa.

Jika fungsi gagal, nilai yang dikembalikan adalah nol.

Keterangan

Pengaturan perataan teks saat ini untuk konteks perangkat yang ditentukan menentukan bagaimana titik referensi digunakan untuk memposisikan teks. Pengaturan perataan teks diambil dengan memanggil fungsi GetTextAlign . Pengaturan perataan teks diubah dengan memanggil fungsi SetTextAlign . Anda bisa menggunakan nilai berikut untuk perataan teks. Hanya satu bendera yang dapat dipilih dari bendera yang memengaruhi perataan horizontal dan vertikal. Selain itu, hanya salah satu dari dua bendera yang mengubah posisi saat ini yang dapat dipilih.

Istilah	Deskripsi
TA_BASELINE	Titik referensi akan berada di baris dasar teks.
TA_BOTTOM	Titik referensi akan berada di tepi bawah persegi panjang pembatas.
TA_TOP	Titik referensi akan berada di tepi atas persegi panjang pembatas.
TA_CENTER	Titik referensi akan diratakan secara horizontal dengan tengah persegi panjang pembatas.
TA_LEFT	Titik referensi akan berada di tepi kiri persegi panjang pembatas.
TA_RIGHT	Titik referensi akan berada di tepi kanan persegi panjang pembatas.
TA_NOUPDATECP	Posisi saat ini tidak diperbarui setelah setiap panggilan output teks. Titik referensi diteruskan ke fungsi output teks.
TA_RTLREADING	Windows edisi bahasa Timur Tengah: Teks ditata dalam urutan baca kanan ke kiri, dibandingkan dengan urutan default kiri ke kanan. Ini hanya berlaku ketika font yang dipilih ke dalam konteks perangkat adalah Ibrani atau Arab.
TA_UPDATECP	Posisi saat ini diperbarui setelah setiap panggilan output teks. Posisi saat ini digunakan sebagai titik referensi.

Jika parameter lpDx adalah NULL, fungsi ExtTextOut menggunakan penspasian default antar karakter. Asal sel karakter dan konten array yang diacu oleh parameter lpDx ditentukan dalam unit logis. Asal sel karakter didefinisikan sebagai sudut kiri atas sel karakter.

Secara default, posisi saat ini tidak digunakan atau diperbarui oleh fungsi ini. Namun, aplikasi dapat memanggil fungsi SetTextAlign dengan parameter fMode diatur ke TA_UPDATECP untuk mengizinkan sistem menggunakan dan memperbarui posisi saat ini setiap kali aplikasi memanggil ExtTextOut untuk konteks perangkat tertentu. Ketika bendera ini diatur, sistem mengabaikan parameter X dan Y pada panggilan ExtTextOut berikutnya.

Untuk versi ANSI dari ExtTextOut, array lpDx memiliki jumlah nilai INT yang sama dengan ada byte dalam lpString. Untuk karakter DBCS, Anda dapat menambahkan dx dalam entri lpDx antara byte prospek dan byte jejak, selama jumlah dua byte ditambahkan ke dx yang diinginkan. Untuk karakter DBCS dengan versi Unicode ExtTextOut, setiap glyph Unicode mendapatkan entri pdx tunggal.

Catatan, nilai alpDx dari GetTextExtentExPoint tidak sama dengan nilai lpDx untuk ExtTextOut. Untuk menggunakan nilai alpDx di lpDx, Anda harus terlebih dahulu memprosesnya.

ExtTextOut akan menggunakan Uniscribe jika perlu menghasilkan fallback font. Bendera ETO_IGNORELANGUAGE akan menghambat perilaku ini dan tidak boleh diteruskan.

Selain itu, ExtTextOut akan melakukan batching panggilan internal sebelum beralih ke mode kernel, mengurangi beberapa masalah performa saat menimbang penggunaan PolyTextOut versus ExtTextOut.

Tip

ExtTextOut sangat direkomendasikan daripada PolyTextOut untuk pengembangan modern karena kemampuannya untuk menangani tampilan bahasa yang berbeda.

Contoh

Misalnya, lihat "Mengatur Font untuk Menu-Item String Teks" di Menggunakan Menu.

Catatan

Header wingdi.h mendefinisikan ExtTextOut sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praproscessor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

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	wingdi.h (sertakan Windows.h)
Pustaka	Gdi32.lib
DLL	Gdi32.dll