struktur GCP_RESULTSA (wingdi.h)
Struktur GCP_RESULTS berisi informasi tentang karakter dalam string. Struktur ini menerima hasil fungsi GetCharacterPlacement . Untuk beberapa bahasa, elemen pertama dalam array mungkin berisi lebih banyak informasi yang bergantung pada bahasa.
Sintaks
typedef struct tagGCP_RESULTSA {
DWORD lStructSize;
LPSTR lpOutString;
UINT *lpOrder;
int *lpDx;
int *lpCaretPos;
LPSTR lpClass;
LPWSTR lpGlyphs;
UINT nGlyphs;
int nMaxFit;
} GCP_RESULTSA, *LPGCP_RESULTSA;
Anggota
lStructSize
Ukuran struktur dalam byte.
lpOutString
Penunjuk ke buffer yang menerima string output atau NULL jika string output tidak diperlukan. String output adalah versi string asli yang dalam urutan yang akan ditampilkan pada perangkat tertentu. Biasanya string output identik dengan string asli, tetapi mungkin berbeda jika string perlu diurutkan ulang dan bendera GCP_REORDER diatur atau jika string asli melebihi batas maksimum dan bendera GCP_MAXEXTENT diatur.
lpOrder
Penunjuk ke array yang menerima indeks pengurutan atau NULL jika indeks pengurutan tidak diperlukan. Namun, maknanya tergantung pada elemen GCP_RESULTS lainnya. Jika indeks glyph akan dikembalikan, indeksnya adalah untuk array lpGlyphs ; jika indeks glyphs tidak dikembalikan dan lpOrder diminta, indeksnya adalah untuk lpOutString. Misalnya, dalam kasus terakhir nilai lpOrder[i] adalah posisi lpString[i] dalam string output lpOutString.
Ini biasanya digunakan ketika GetFontLanguageInfo mengembalikan bendera GCP_REORDER, yang menunjukkan bahwa string asli perlu diurutkan ulang. Misalnya, dalam bahasa Ibrani, di mana teks berjalan dari kanan ke kiri, array lpOrder memberikan lokasi yang tepat dari setiap elemen dalam string asli.
lpDx
Penunjuk ke array yang menerima jarak antara sel karakter yang berdekatan atau NULL jika jarak ini tidak diperlukan. Jika penyajian glyph selesai, jaraknya adalah untuk glyph bukan karakter, sehingga array yang dihasilkan dapat digunakan dengan fungsi ExtTextOut .
Jarak dalam array ini dalam urutan tampilan. Untuk menemukan jarak untuk karakter ith dalam string asli, gunakan array lpOrder sebagai berikut:
width = lpDx[lpOrder[i]];
lpCaretPos
Penunjuk ke array yang menerima nilai posisi tanda sisipan atau NULL jika posisi tanda sisipan tidak diperlukan. Setiap nilai menentukan posisi tanda sisipan segera sebelum karakter yang sesuai. Dalam beberapa bahasa posisi tanda sisipan untuk setiap karakter mungkin tidak segera berada di sebelah kiri karakter. Misalnya, dalam bahasa Ibrani, di mana teks berjalan dari kanan ke kiri, posisi tanda sisipan berada di sebelah kanan karakter. Jika pengurutan glyph dilakukan, lpCaretPos cocok dengan string asli, bukan string output. Ini berarti bahwa beberapa nilai yang berdekatan mungkin sama.
Nilai dalam array ini berada dalam urutan input. Untuk menemukan nilai posisi tanda sisipan untuk karakter ith dalam string asli, gunakan array sebagai berikut:
position = lpCaretPos[i];
lpClass
Penunjuk ke array yang berisi dan/atau menerima klasifikasi karakter. Nilai menunjukkan cara menata letak karakter dalam string dan serupa (tetapi tidak identik) dengan nilai CT_CTYPE2 yang dikembalikan oleh fungsi GetStringTypeEx . Setiap elemen array dapat diatur ke nol atau salah satu nilai berikut.
Selain itu, berikut ini dapat digunakan saat menyediakan nilai dalam array lpClass dengan bendera GCP_CLASSIN.
Untuk bahasa yang menggunakan bendera GCP_REORDER, nilai berikut juga dapat digunakan dengan bendera GCP_CLASSIN. Tidak seperti nilai sebelumnya, yang dapat digunakan di mana saja dalam array lpClass , semua nilai berikut hanya digunakan di lokasi pertama dalam array. Semua digabungkan dengan klasifikasi lainnya.
Perhatikan bahwa GCPCLASS_PREBOUNDLTR dan GCPCLASS_PREBOUNDRTL saling eksklusif, seperti halnya GCPCLASSPOSTBOUNDLTR dan GCPCLASSPOSTBOUNDRTL.
Untuk memaksa tata letak karakter dilakukan dengan cara tertentu, prasetel klasifikasi untuk elemen array yang sesuai; fungsi ini membuat klasifikasi prasetel tersebut tidak berubah dan menghitung klasifikasi hanya untuk elemen array yang telah diatur ke nol. Klasifikasi prasetel hanya digunakan jika bendera GCP_CLASSIN diatur dan array lpClass disediakan.
Jika GetFontLanguageInfo tidak mengembalikan GCP_REORDER untuk font saat ini, hanya nilai GCPCLASS_LATIN yang bermakna.
lpGlyphs
Penunjuk ke array yang menerima nilai yang mengidentifikasi glyph yang digunakan untuk merender string atau NULL jika penyajian glyph tidak diperlukan. Jumlah glyph dalam array mungkin kurang dari jumlah karakter dalam string asli jika string berisi glyph ligated. Juga jika pengurutan ulang diperlukan, urutan glyph mungkin tidak berurutan.
Array ini berguna jika lebih dari satu operasi sedang dilakukan pada string yang memiliki segala bentuk ligasi, kerning, atau peralihan pesanan. Menggunakan nilai dalam array ini untuk operasi berikutnya menghemat waktu jika tidak diperlukan untuk menghasilkan indeks glyph setiap kali.
Array ini selalu berisi indeks glyph dan nilai ETO_GLYPH_INDEX harus selalu digunakan ketika array ini digunakan dengan fungsi ExtTextOut .
Saat GCP_LIGATE digunakan, Anda dapat membatasi jumlah karakter yang akan dibariskan bersama-sama. (Dalam bahasa Arab misalnya, ligasi tiga karakter adalah umum). Ini dilakukan dengan mengatur maksimum yang diperlukan dalam lpGcpResults-lpGlyphs>[0]. Jika tidak ada maksimum yang diperlukan, Anda harus mengatur bidang ini ke nol.
Untuk bahasa seperti Arab, di mana GetFontLanguageInfo mengembalikan bendera GCP_GLYPHSHAPE, glyph untuk karakter akan berbeda tergantung pada apakah karakter berada di awal, tengah, atau akhir kata. Biasanya, karakter pertama dalam string input juga akan menjadi karakter pertama dalam sebuah kata, dan karakter terakhir dalam string input akan diperlakukan sebagai karakter terakhir dalam sebuah kata. Namun, jika string yang ditampilkan adalah subset dari string lengkap, seperti saat menampilkan bagian teks yang digulir, ini mungkin tidak benar. Dalam kasus ini, diinginkan untuk memaksa karakter pertama atau terakhir dibentuk sebagai bukan bentuk awal atau akhir. Untuk melakukan ini, sekali lagi, lokasi pertama dalam array lpGlyphs digunakan dengan melakukan operasi OR dari nilai ligasi di atas dengan nilai GCPGLYPH_LINKBEFORE dan/atau GCPGLYPH_LINKAFTER. Misalnya, nilai GCPGLYPH_LINKBEFORE | 2 berarti bahwa ligatur dua karakter adalah maksimum yang diperlukan, dan karakter pertama dalam string harus diperlakukan seolah-olah berada di tengah kata.
nGlyphs
Pada input, anggota ini harus diatur ke ukuran array yang ditujukkan oleh anggota penunjuk array. Pada output, ini diatur ke jumlah glyph yang diisi, dalam array output. Jika substitusi glyph tidak diperlukan (yaitu, setiap karakter input memetakan ke tepat satu glyph), anggota ini sama seperti pada input.
nMaxFit
Jumlah karakter yang sesuai dalam jangkauan yang ditentukan oleh parameter nMaxExtent dari fungsi GetCharacterPlacement . Jika nilai GCP_MAXEXTENT atau GCP_JUSTIFY diatur, nilai ini mungkin kurang dari jumlah karakter dalam string asli. Anggota ini diatur terlepas dari apakah nilai GCP_MAXEXTENT atau GCP_JUSTIFY ditentukan. Tidak seperti nGlyphs, yang menentukan jumlah glyph output, nMaxFit mengacu pada jumlah karakter dari string input. Untuk bahasa SBCS Latin, ini akan sama.
Keterangan
Apakah lpGlyphs, lpOutString, atau tidak diperlukan tergantung pada hasil panggilan GetFontLanguageInfo .
Dalam kasus font untuk bahasa seperti bahasa Inggris, di mana tidak ada bendera GCP_DBCS, GCP_REORDER, GCP_GLYPHSHAPE, GCP_LIGATE, GCP_DIACRITIC, atau GCP_KASHIDA yang dikembalikan, tidak ada array yang diperlukan untuk operasi yang tepat. (Meskipun tidak diperlukan, mereka masih dapat digunakan. Jika array lpOutString digunakan, array tersebut akan sama persis dengan lpInputString yang diteruskan ke GetCharacterPlacement.) Namun, perhatikan bahwa jika GCP_MAXEXTENT digunakan, maka lpOutString akan berisi string yang terpotong jika digunakan, BUKAN salinan asli yang tepat.
Dalam kasus font untuk bahasa seperti Ibrani, yang DO miliki susun ulang tetapi biasanya tidak memiliki bentuk glyph ekstra, lpOutString harus digunakan. Ini akan memberikan string pada urutan yang dapat dibaca layar. Namun, array lpGlyphs biasanya tidak diperlukan. (Bahasa Ibrani dapat memiliki glyph tambahan, jika fontnya adalah font TrueType/Open.)
Dalam kasus bahasa seperti Thailand atau Arab, di mana GetFontLanguageInfo mengembalikan bendera GCP_GLYPHSHAPE, lpOutString akan memberikan urutan string yang dapat dibaca tampilan yang diteruskan ke GetCharacterPlacement, tetapi nilainya masih akan menjadi karakter yang tidak diblokir. Untuk tampilan yang tepat, array lpGlyphs harus digunakan.
Catatan
Header wingdi.h mendefinisikan GCP_RESULTS 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] |
| Header | wingdi.h (sertakan Windows.h) |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk