Fungsi GetCharacterPlacementA (wingdi.h)

Artikel
08/03/2023

Fungsi GetCharacterPlacement mengambil informasi tentang string karakter, seperti lebar karakter, penempatan tanda sisipan, pengurutan dalam string, dan penyajian glyph. Jenis informasi yang dikembalikan tergantung pada parameter dwFlags dan didasarkan pada font yang saat ini dipilih dalam konteks tampilan yang ditentukan. Fungsi menyalin informasi ke struktur GCP_RESULTS yang ditentukan atau ke satu atau beberapa array yang ditentukan oleh struktur.

Meskipun fungsi ini pernah memadai untuk bekerja dengan string karakter, kebutuhan untuk bekerja dengan meningkatnya jumlah bahasa dan skrip telah merendernya usang. Ini telah digantikan oleh fungsionalitas modul Uniscribe. Untuk informasi selengkapnya, lihat Uniscribe.

Disarankan agar aplikasi menggunakan fungsi GetFontLanguageInfo untuk menentukan apakah nilai GCP_DIACRITIC, GCP_DBCS, GCP_USEKERNING, GCP_LIGATE, GCP_REORDER, GCP_GLYPHSHAPE, dan GCP_KASHIDA valid untuk font yang saat ini dipilih. Jika tidak valid, GetCharacterPlacement mengabaikan nilai.

Nilai GCP_NODIACRITICS tidak lagi ditentukan dan tidak boleh digunakan.

Sintaksis

DWORD GetCharacterPlacementA(
  [in]      HDC            hdc,
  [in]      LPCSTR         lpString,
  [in]      int            nCount,
  [in]      int            nMexExtent,
  [in, out] LPGCP_RESULTSA lpResults,
  [in]      DWORD          dwFlags
);

Parameter

[in] hdc

Handel ke konteks perangkat.

[in] lpString

Penunjuk ke string karakter untuk diproses. String tidak perlu dihentikan nol, karena nCount menentukan panjang string.

[in] nCount

Panjang string ditujukkan oleh lpString.

[in] nMexExtent

Tingkat maksimum (dalam unit logis) tempat string diproses. Karakter yang, jika diproses, akan melebihi batas ini diabaikan. Komputasi untuk pengurutan atau array glyph yang diperlukan hanya berlaku untuk karakter yang disertakan. Parameter ini hanya digunakan jika nilai GCP_MAXEXTENT ditentukan dalam parameter dwFlags. Saat fungsi memproses string input, setiap karakter dan tingkatnya ditambahkan ke output, luas, dan array lainnya hanya jika tingkat total belum melebihi maksimum. Setelah batas tercapai, pemrosesan akan berhenti.

[in, out] lpResults

Penunjuk ke struktur GCP_RESULTS yang menerima hasil fungsi.

[in] dwFlags

Menentukan cara memproses string ke dalam array yang diperlukan. Parameter ini bisa berupa satu atau beberapa nilai berikut.

Nilai	Arti
GCP_CLASSIN	Menentukan bahwa array lpClass berisi klasifikasi prasetel untuk karakter. Klasifikasi mungkin sama seperti pada output. Jika klasifikasi tertentu untuk karakter tidak diketahui, lokasi terkait dalam array harus diatur ke nol. untuk informasi selengkapnya tentang klasifikasi, lihat GCP_RESULTS. Ini hanya berguna jika GetFontLanguageInfo mengembalikan bendera GCP_REORDER.
GCP_DIACRITIC	Menentukan bagaimana diakritik dalam string ditangani. Jika nilai ini tidak diatur, diakritik diperlakukan sebagai karakter lebar nol. Misalnya, string Ibrani mungkin berisi diakritik, tetapi Anda mungkin tidak ingin menampilkannya. Gunakan GetFontLanguageInfo untuk menentukan apakah font mendukung diakritik. Jika ya, Anda dapat menggunakan atau tidak menggunakan bendera GCP_DIACRITIC dalam panggilan ke GetCharacterPlacement, tergantung pada kebutuhan aplikasi Anda.
GCP_DISPLAYZWG	Untuk bahasa yang perlu diurutkan ulang atau bentuk glyph yang berbeda tergantung pada posisi karakter dalam kata, karakter yang tidak dapat diputar sering muncul di halaman kode. Misalnya, di halaman kode Ibrani, ada penanda Left-To-Right dan Right-To-Left, untuk membantu menentukan posisi akhir karakter dalam string output. Biasanya ini tidak ditampilkan dan dihapus dari lpGlyphs dan array lpDx . Anda dapat menggunakan bendera GCP_DISPLAYZWG untuk menampilkan karakter ini.
GCP_GLYPHSHAPE	Menentukan bahwa beberapa atau semua karakter dalam string akan ditampilkan menggunakan bentuk selain bentuk standar yang ditentukan dalam font yang saat ini dipilih untuk halaman kode saat ini. Beberapa bahasa, seperti Arab, tidak dapat mendukung pembuatan glyph kecuali nilai ini ditentukan. Sebagai aturan umum, jika GetFontLanguageInfo mengembalikan nilai ini untuk string, nilai ini harus digunakan dengan GetCharacterPlacement.
GCP_JUSTIFY	Menyesuaikan tingkat dalam array lpDx sehingga panjang string sama dengan nMaxExtent. GCP_JUSTIFY hanya dapat digunakan bersama dengan GCP_MAXEXTENT.
GCP_KASHIDA	Gunakan Kashidas serta, atau alih-alih, batas yang disesuaikan untuk memodifikasi panjang string sehingga sama dengan nilai yang ditentukan oleh nMaxExtent. Dalam array lpDx , Kashida ditunjukkan oleh indeks pertimbangan negatif. GCP_KASHIDA hanya dapat digunakan bersama dengan GCP_JUSTIFY dan hanya jika font (dan bahasa) mendukung Kashidas. Gunakan GetFontLanguageInfo untuk menentukan apakah font saat ini mendukung Kashidas. Menggunakan Kashidas untuk membenarkan string dapat mengakibatkan jumlah glyph yang diperlukan lebih besar dari jumlah karakter dalam string input. Karena itu, ketika Kashidas digunakan, aplikasi tidak dapat mengasumsikan bahwa mengatur array menjadi ukuran string input akan cukup. (Kemungkinan maksimum adalah sekitar dxPageWidth/dxAveCharWidth, di mana dxPageWidth adalah lebar dokumen dan dxAveCharWidth adalah lebar karakter rata-rata seperti yang dikembalikan dari panggilan GetTextMetrics). Perhatikan bahwa hanya karena GetFontLanguageInfo mengembalikan bendera GCP_KASHIDA tidak berarti bahwa itu harus digunakan dalam panggilan ke GetCharacterPlacement, hanya saja opsi tersedia.
GCP_LIGATE	Gunakan ligasi di mana pun karakter berada. Ligasi terjadi di mana satu glyph digunakan untuk dua karakter atau lebih. Misalnya, huruf a dan e dapat dilimpahkan ke ?. Namun, agar ini digunakan, baik dukungan bahasa maupun font harus mendukung glyph yang diperlukan (contoh tidak akan diproses secara default dalam bahasa Inggris). Gunakan GetFontLanguageInfo untuk menentukan apakah font saat ini mendukung ligasi. Jika ya dan maksimum tertentu diperlukan untuk jumlah karakter yang akan memisah, atur angka dalam elemen pertama lpGlyphs array. Jika ligasi normal diperlukan, atur nilai ini ke nol. Jika GCP_LIGATE tidak ditentukan, tidak ada ligasi yang akan terjadi. Lihat GCP_RESULTS untuk informasi selengkapnya. Jika nilai GCP_REORDER biasanya diperlukan untuk set karakter tetapi tidak ditentukan, output tidak akan berarti kecuali string yang diteruskan sudah dalam urutan visual (yaitu, hasil yang dimasukkan ke dalam lpGcpResults->lpOutString dalam satu panggilan ke GetCharacterPlacement adalah string input panggilan kedua). Perhatikan bahwa hanya karena GetFontLanguageInfo mengembalikan bendera GCP_LIGATE tidak berarti bahwa itu harus digunakan dalam panggilan ke GetCharacterPlacement, hanya saja opsi tersedia.
GCP_MAXEXTENT	Tingkat komputasi string hanya selama tingkat yang dihasilkan, dalam unit logis, tidak melebihi nilai yang ditentukan oleh parameter nMaxExtent.
GCP_NEUTRALOVERRIDE	Bahasa tertentu saja. Ambil alih penanganan normal netral dan perlakukan sebagai karakter kuat yang cocok dengan urutan pembacaan string. Hanya berguna dengan bendera GCP_REORDER.
GCP_NUMERICOVERRIDE	Bahasa tertentu saja. Ambil alih penanganan numerik normal dan perlakukan sebagai karakter kuat yang cocok dengan urutan pembacaan string. Hanya berguna dengan bendera GCP_REORDER.
GCP_NUMERICSLATIN	Arab/Thailand saja. Gunakan glyph Latin standar untuk angka dan ambil alih default sistem. Untuk menentukan apakah opsi ini tersedia dalam bahasa font, gunakan GetStringTypeEx untuk melihat apakah bahasa mendukung lebih dari satu format angka.
GCP_NUMERICSLOCAL	Arab/Thailand saja. Gunakan glyph lokal untuk karakter numerik dan ambil alih default sistem. Untuk menentukan apakah opsi ini tersedia dalam bahasa font, gunakan GetStringTypeEx untuk melihat apakah bahasa mendukung lebih dari satu format angka.
GCP_REORDER	Menyusun ulang string. Gunakan untuk bahasa yang bukan SBCS dan urutan baca kiri-ke-kanan. Jika nilai ini tidak ditentukan, string diasumsikan sudah dalam urutan tampilan. Jika bendera ini diatur untuk bahasa Semitic dan array lpClass digunakan, dua elemen pertama array digunakan untuk menentukan urutan pembacaan di luar batas string. GCP_CLASS_PREBOUNDRTL dan GCP_CLASS_PREBOUNDLTR dapat digunakan untuk mengatur pesanan. Jika tidak ada urutan prasetel yang diperlukan, atur nilai ke nol. Nilai-nilai ini dapat dikombinasikan dengan nilai lain jika bendera GCPCLASSIN diatur. Jika nilai GCP_REORDER tidak ditentukan, parameter lpString diambil untuk diurutkan secara visual untuk bahasa tempat ini digunakan, dan lpOutString dan lpOrder bidang diabaikan. Gunakan GetFontLanguageInfo untuk menentukan apakah font saat ini mendukung penyortirusan ulang.
GCP_SYMSWAPOFF	Bahasa semitik saja. Menentukan bahwa karakter yang dapat ditukar tidak diatur ulang. Misalnya, dalam string kanan-ke-kiri, '(' dan ')' tidak dibalik.
GCP_USEKERNING	Gunakan pasangan kerning dalam font (jika ada) saat membuat array lebar. Gunakan GetFontLanguageInfo untuk menentukan apakah font saat ini mendukung pasangan kerning. Perhatikan bahwa hanya karena GetFontLanguageInfo mengembalikan bendera GCP_USEKERNING tidak berarti bahwa itu harus digunakan dalam panggilan untuk GetCharacterPlacement, hanya bahwa opsi tersedia. Sebagian besar font TrueType memiliki tabel kerning, tetapi Anda tidak perlu menggunakannya.

Nilai GCP_NODIACRITICS tidak lagi ditentukan dan tidak boleh digunakan.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah lebar dan tinggi string dalam unit logis. Lebar adalah kata berurutan rendah dan tingginya adalah kata berurutan tinggi.

Jika fungsi gagal, nilai yang dikembalikan adalah nol.

Komentar

GetCharacterPlacement memastikan bahwa aplikasi dapat memproses teks dengan benar terlepas dari pengaturan internasional dan jenis font yang tersedia. Aplikasi menggunakan fungsi ini sebelum menggunakan fungsi ExtTextOut dan menggantikan fungsi GetTextExtentPoint32 (dan kadang-kadang menggantikan GetCharWidth32 dan GetCharABCWidths fungsi).

Menggunakan GetCharacterPlacement untuk mengambil penspasian antarkarakter dan array indeks tidak selalu diperlukan kecuali pembenaran atau kerning diperlukan. Untuk font non-Latin, aplikasi dapat meningkatkan kecepatan fungsi ExtTextOut merender teks dengan menggunakan GetCharacterPlacement untuk mengambil spasi intercharacter dan array indeks sebelum memanggil ExtTextOut. Ini sangat berguna saat merender teks yang sama berulang kali atau saat menggunakan penspasian antarkarakter untuk memosisikan tanda sisipan. Jika lpGlyphs output array digunakan dalam panggilan ke ExtTextOut, bendera ETO_GLYPH_INDEX harus diatur.

GetCharacterPlacement memeriksalpOrder , lpDX, lpCaretPos, lp OutString, dan lpGlyphs anggota struktur GCP_RESULTS dan mengisi array yang sesuai jika anggota ini tidak diatur ke NULL. Jika GetCharacterPlacement tidak dapat mengisi array, ia mengatur anggota yang sesuai ke NULL. Untuk memastikan pengambilan informasi yang valid, aplikasi bertanggung jawab untuk mengatur anggota ke alamat yang valid sebelum memanggil fungsi dan untuk memeriksa nilai anggota setelah panggilan. Jika nilai GCP_JUSTIFY atau GCP_USEKERNING ditentukan, lpDX dan/atau anggota lpCaretPos harus memiliki alamat yang valid.

Perhatikan bahwa indeks glyph yang dikembalikan dalam GCP_RESULTS.lpGlyphs khusus untuk font saat ini dalam konteks perangkat dan hanya boleh digunakan untuk menggambar teks dalam konteks perangkat sementara font tersebut tetap dipilih.

Saat pembenaran komputasi, jika karakter berikutnya dalam string adalah spasi, fungsi mengurangi panjang string dan menghapus spasi sebelum menghitung pembenaran. Jika array hanya terdiri dari spasi, fungsi mengembalikan kesalahan.

ExtTextOut mengharapkan entri lpDX untuk setiap byte string DBCS, sedangkan GetCharacterPlacement menetapkan entri lpDX untuk setiap glyph. Untuk memperbaiki ketidakcocokan ini saat menggunakan kombinasi fungsi ini, gunakan GetGlyphIndices atau perluas array lpDX dengan entri lebar nol untuk byte kedua yang sesuai dari pasangan byte DBCS.

Jika lebar logika kurang dari lebar karakter utama dalam string input, GCP_RESULTS.nMaxFit mengembalikan nilai yang buruk. Untuk kasus ini, panggil GetCharacterPlacement untuk indeks glyph dan array lpDX. Kemudian gunakan array lpDX untuk melakukan perhitungan tingkat lanjut menggunakan lebar lanjutan setiap karakter, di mana nMaxFit adalah jumlah karakter yang indeks glyph-nya lebar maju kurang dari lebar karakter utama.

Catatan

Header wingdi.h mendefinisikan GetCharacterPlacement sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta preprosektor 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

Syarat	Nilai
klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Platform Target	Windows
Header	wingdi.h (termasuk Windows.h)
Pustaka	Gdi32.lib
DLL	Gdi32.dll

Lihat juga

ExtTextOut

Fungsi Font dan Teks

Font dan Gambaran Umum Teks

GCP_RESULTS

GetCharABCWidths

GetCharWidth32

GetFontLanguageInfo

GetStringTypeEx

getTextExtentPoint32

GetTextMetrics

Festival Keterampilan AI

Bagikan melalui