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 dependen bahasa.

Sintaksis

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, dalam byte, dari struktur.

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 tingkat 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 lain dari GCP_RESULTS. Jika indeks glyph akan dikembalikan, indeks 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 karakter idalam 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 dalam urutan input. Untuk menemukan nilai posisi tanda sisipan untuk karakter i^th 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 membiarkan 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 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.

Komentar

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 diteruskan ke GetCharacterPlacement.) Namun, perhatikan bahwa jika GCP_MAXEXTENT digunakan, maka lpOutString akan berisi string 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 tambahan, lpOutString harus digunakan. Ini akan memberikan string pada urutan yang dapat dibaca layar. Namun, array lpGlyphs biasanya tidak diperlukan. (Ibrani dapat memiliki glyph tambahan, jika font 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.

Persyaratan

Lihat juga

ExtTextOut

Font dan Teks

Font dan Gambaran Umum Teks

GetCharacterPlacement

GetFontLanguageInfo