Fungsi GetCharacterPlacementA (wingdi.h)

Artikel
03/08/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 membuatnya 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.

Sintaks

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 yang ditujukkan oleh lpString.

[in] nMexExtent

Jangkauan maksimum (dalam unit logis) tempat string diproses. Karakter yang, jika diproses, akan melebihi batas ini diabaikan. Komputasi untuk setiap 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 jangkauannya ditambahkan ke output, jangkauan, 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 menjadi satu atau beberapa nilai berikut.

Nilai	Makna
GCP_CLASSIN	Menentukan bahwa array lpClass berisi klasifikasi preset untuk karakter. Klasifikasi mungkin sama dengan pada output. Jika klasifikasi tertentu untuk karakter tidak diketahui, lokasi yang sesuai 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 Kiri-Ke-Kanan dan Kanan-Ke-Kiri, untuk membantu menentukan penempatan akhir karakter dalam string output. Biasanya ini tidak ditampilkan dan dihapus dari array lpGlyphs dan 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 jangkauan 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, menyesuaikan jangkauan untuk memodifikasi panjang string sehingga sama dengan nilai yang ditentukan oleh nMaxExtent. Dalam array lpDx , Kashida ditunjukkan oleh indeks pembenaran 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 dapat digunakan, baik dukungan bahasa maupun font harus mendukung glyph yang diperlukan (contohnya 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 ligate, atur angka dalam elemen pertama array lpGlyphs . 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 sejauh 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 normal numerik dan perlakukan sebagai karakter kuat yang cocok dengan urutan pembacaan string. Hanya berguna dengan bendera GCP_REORDER.
GCP_NUMERICSLATIN	Arab/Thailand saja. Gunakan latin glyph 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 di mana ini digunakan, dan bidang lpOutString dan lpOrder diabaikan. Gunakan GetFontLanguageInfo untuk menentukan apakah font saat ini mendukung pengurusan ulang.
GCP_SYMSWAPOFF	Hanya bahasa semitik. 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 ke GetCharacterPlacement, hanya saja 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 urutan rendah dan tingginya adalah kata urutan tinggi.

Jika fungsi gagal, nilai yang dikembalikan adalah nol.

Keterangan

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 fungsi GetCharWidth32 dan GetCharABCWidths ).

Menggunakan GetCharacterPlacement untuk mengambil penspasian intercharacter 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 spasi antarkarakter untuk memposisikan tanda sisipan. Jika array output lpGlyphs digunakan dalam panggilan ke ExtTextOut, bendera ETO_GLYPH_INDEX harus diatur.

GetCharacterPlacement memeriksa anggota lpOrder, lpDX, lpCaretPos, lpOutString, dan lpGlyphs dari 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, anggota lpDX dan/atau lpCaretPos harus memiliki alamat yang valid.

Perhatikan bahwa indeks glyph yang dikembalikan di 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 jangkauan menggunakan lebar lanjutan dari 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 pra-prosesor 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