Fungsi ScriptItemizeOpenType (usp10.h)

Artikel
08/26/2023

Memecah string Unicode menjadi item yang dapat dibentuk secara individual dan menyediakan array tag fitur untuk setiap item yang dapat dibentuk untuk pemrosesan OpenType.

Sintaks

HRESULT ScriptItemizeOpenType(
  [in]           const WCHAR          *pwcInChars,
  [in]           int                  cInChars,
  [in]           int                  cMaxItems,
  [in, optional] const SCRIPT_CONTROL *psControl,
  [in, optional] const SCRIPT_STATE   *psState,
  [out]          SCRIPT_ITEM          *pItems,
  [out]          OPENTYPE_TAG         *pScriptTags,
  [out]          int                  *pcItems
);

Parameter

[in] pwcInChars

Arahkan ke string Unicode untuk itemisasi.

[in] cInChars

Jumlah karakter dalam pwcInChars yang akan diperinci.

[in] cMaxItems

Jumlah maksimum struktur SCRIPT_ITEM yang menentukan item untuk diproses.

[in, optional] psControl

Penunjuk ke struktur SCRIPT_CONTROL yang menunjukkan jenis itemisasi yang akan dilakukan.

Atau, aplikasi dapat mengatur parameter ini ke NULL jika tidak ada properti SCRIPT_CONTROL yang diperlukan. Untuk informasi lebih lanjut, lihat bagian Keterangan.

[in, optional] psState

Penunjuk ke struktur SCRIPT_STATE yang menunjukkan status algoritma dua arah awal.

Atau, aplikasi dapat mengatur parameter ini ke NULL jika status skrip tidak diperlukan. Untuk informasi lebih lanjut, lihat bagian Keterangan.

[out] pItems

Penunjuk ke buffer tempat fungsi mengambil struktur SCRIPT_ITEM yang mewakili item yang telah diproses. Panjang buffer harus (cMaxItems + 1) * sizeof(SCRIPT_ITEM) byte. Tidak valid untuk memanggil fungsi ini dengan buffer yang menangani kurang dari dua struktur SCRIPT_ITEM . Fungsi selalu menambahkan item terminal ke array analisis item sehingga panjang item dengan indeks berbasis nol "i" selalu tersedia sebagai:

pItems[i+1].iCharPos - pItems[i].iCharPos;

[out] pScriptTags

Penunjuk ke buffer di mana fungsi mengambil array struktur OPENTYPE_TAG yang mewakili tag skrip. Panjang buffer harus cMaxItems * sizeof(OPENTYPE_TAG) byte.

Catatan Ketika semua karakter dalam item netral, nilai parameter ini SCRIPT_TAG_UNKNOWN (0x00000000). Ini dapat terjadi, misalnya, jika item sepenuhnya terdiri dari tanda baca.

[out] pcItems

Arahkan ke jumlah struktur SCRIPT_ITEM yang diproses.

Nilai kembali

Mengembalikan 0 jika berhasil. Fungsi mengembalikan nilai HRESULT bukan nol jika tidak berhasil. Dalam semua kasus kesalahan, tidak ada item yang sepenuhnya diproses dan tidak ada bagian dari output yang berisi nilai yang ditentukan. Aplikasi dapat menguji nilai pengembalian dengan makro BERHASIL dan GAGAL .

Fungsi mengembalikan E_OUTOFMEMORY jika ukuran yang ditunjukkan oleh cMaxItems terlalu kecil. Aplikasi dapat mencoba memanggil fungsi lagi dengan buffer yang lebih besar.

Fungsi mengembalikan E_INVALIDARG jika satu atau beberapa kondisi berikut terjadi:

pwcInChars diatur ke NULL
cInChars adalah 0
pItem diatur ke NULL
pScriptTags diatur ke NULL
cMaxItems< 2

Keterangan

ScriptItemizeOpenType lebih disukai daripada fungsi ScriptItemize yang lebih lama. Salah satu keuntungan dari ScriptItemizeOpenType adalah ketersediaan tag fitur untuk setiap item yang dapat dibentuk.

Lihat Menampilkan Teks dengan Uniscribe untuk diskusi konteks di mana fungsi ini biasanya dipanggil.

Fungsi ini memisahkan item dengan perubahan mesin pembentukan atau perubahan arah.

Aplikasi dapat membuat beberapa rentang, atau menjalankan yang sepenuhnya berada dalam satu item, dari setiap struktur SCRIPT_ITEM yang diambil oleh ScriptItemizeOpenType. Namun, tidak boleh menggabungkan beberapa item ke dalam satu eksekusi. Saat mengukur atau merender, aplikasi dapat memanggil ScriptShapeOpenType untuk setiap proses dan harus melewati struktur SCRIPT_ANALYSIS yang sesuai dalam struktur SCRIPT_ITEM yang diambil oleh ScriptItemizeOpenType.

Jika teks yang ditangani oleh aplikasi dapat menyertakan konten kanan-ke-kiri, aplikasi menggunakan parameter psControl dan psState dalam memanggil ScriptItemizeOpenType. Namun, aplikasi tidak harus melakukan ini dan dapat menangani teks dua arah itu sendiri alih-alih mengandalkan Uniscribe untuk melakukannya. Parameter psControl dan psState berguna dalam beberapa skenario kiri-ke-kanan yang ketat, misalnya, ketika anggota fLinkStringBeforeSCRIPT_CONTROL tidak spesifik untuk skrip kanan-ke-kiri. Aplikasi mengatur psControl dan psState ke NULL agar ScriptItemizeOpenType memutus string Unicode murni menurut kode karakter.

Aplikasi dapat mengatur semua parameter ke nilai non-NULL agar fungsi melakukan analisis dua arah Unicode penuh. Untuk mengizinkan analisis dua arah Unicode yang benar, struktur SCRIPT_STATE harus diinisialisasi sesuai dengan urutan pembacaan pada awal paragraf, dan ScriptItemizeOpenType harus melewati seluruh paragraf. Secara khusus, anggota uBidiLevel harus diinisialisasi ke 0 untuk kiri-ke-kanan dan 1 untuk kanan-ke-kiri.

Anggota fRTLSCRIPT_ANALYSIS direferensikan dalam SCRIPT_ITEM. Anggota fNumericSCRIPT_PROPERTIES diambil oleh ScriptGetProperties. Anggota ini bersama-sama memberikan klasifikasi yang sama dengan anggota lpClassGCP_RESULTS, yang dirujuk oleh lpResults di GetCharacterPlacement.

Digit Eropa U+0030 hingga U+0039 dapat dirender sebagai digit nasional, seperti yang ditunjukkan dalam tabel berikut.

SCRIPT_STATE.fDigitSubstitute	SCRIPT_CONTROL.fContextDigits	Bentuk digit ditampilkan untuk Unicode U+0030 hingga U+0039
FALSE	Apa pun	Digit Eropa
TRUE	FALSE	Seperti yang ditentukan dalam uDefaultLanguage anggota SCRIPT_CONTROL.
TRUE	TRUE	Sebagai teks kuat sebelumnya, default ke uDefaultLanguage anggota SCRIPT_CONTROL.

Dalam mode digit konteks, salah satu tindakan berikut terjadi:

Jika skrip yang ditentukan oleh uDefaultLanguage berada dalam arah yang sama dengan output, semua digit yang ditemui sebelum huruf pertama dirender dalam bahasa yang ditunjukkan oleh uDefaultLanguage.
Jika skrip yang ditentukan oleh uDefaultLanguage berada dalam arah yang berlawanan dari output, semua digit yang ditemui sebelum huruf pertama dirender dalam digit Eropa.

Misalnya, jika uDefaultLanguage menunjukkan LANG_ARABIC, digit awal berada di Arabic-Indic dalam penyematan kanan ke kiri. Namun mereka berada di digit Eropa dalam penyematan kiri-ke-kanan.

Untuk informasi selengkapnya, lihat Bentuk Digit.

Karakter dan definisi kontrol Unicode, dan efeknya pada anggota SCRIPT_STATE , disediakan dalam tabel berikut. Untuk informasi selengkapnya tentang karakter kontrol Unicode, lihat Standar Unicode.

Karakter kontrol Unicode	Makna	Pengaruh terhadap SCRIPT_STATE
NAD	Ganti digit Eropa (NODS) dengan bentuk digit nasional.	Atur fDigitSubstitute.
MENGANGGUK	Gunakan bentuk digit nominal, atau dikenal sebagai digit Eropa. Lihat NAD.	Bersihkan fDigitSubstitute.
PANTAT	Aktifkan pertukaran pasangan simetris, misalnya, tanda kurung. Untuk karakter ini, kiri dan kanan ditafsirkan sebagai pembukaan dan penutupan. Ini adalah default. Lihat ISS.	Bersihkan fInhibitSymSwap.
ISS	Menghambat pertukaran pasangan simetris. Lihat ASS.	Atur fInhibitSymSwap.
AAFS	Aktifkan pembentukan bentuk Arab untuk formulir presentasi Arab. Lihat IAFS.	Atur fCharShape.
IAFS	Menghambat pembentukan bentuk Arab, yaitu, ligatur dan koneksi kurva, untuk bentuk presentasi Arab. Karakter Arab nominal tidak terpengaruh. Ini adalah default. Lihat AAFS.	Bersihkan fCharShape.

Anggota fArabicNumContextdari SCRIPT_STATE mendukung tampilan angka yang sensitif terhadap konteks dalam teks skrip Arab. Ini menunjukkan apakah digit dirender menggunakan bentuk digit skrip Arab asli atau digit Eropa. Pada awal paragraf, anggota ini biasanya harus diinisialisasi ke TRUE untuk lokal Arab, atau FALSE untuk lokal lainnya. Fungsi memperbarui status skrip saat memproses teks yang kuat.

Parameter output pScriptTags menunjukkan array dengan entri paralel dengan item. Untuk setiap item, fungsi ini mengambil tag skrip yang harus digunakan untuk membentuk di semua operasi berikutnya.

Tag skrip biasanya ditentukan oleh ScriptItemizeOpenType dari karakter input. Jika fungsi mengambil tag skrip tertentu, aplikasi harus meneruskannya ke fungsi lain tanpa perubahan. Namun, ketika karakter netral (misalnya, digit) dan skrip tidak dapat ditentukan, aplikasi harus memilih tag skrip yang sesuai, misalnya, berdasarkan font dan bahasa yang terkait dengan teks.

Penting Dimulai dengan Windows 8: Untuk mempertahankan kemampuan untuk berjalan pada Windows 7, modul yang menggunakan Uniscribe harus menentukan Usp10.lib sebelum gdi32.lib dalam daftar pustakanya.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	usp10.h
Pustaka	Usp10.lib
DLL	Usp10.dll
Redistribusi	Usp10.dll versi 1.600 atau lebih tinggi di Windows XP