Fungsi ScriptStringAnalyse (usp10.h)

Artikel
08/26/2023

Menganalisis string teks biasa.

Sintaks

HRESULT ScriptStringAnalyse(
  [in]           HDC                    hdc,
  [in]           const void             *pString,
  [in]           int                    cString,
  [in]           int                    cGlyphs,
  [in]           int                    iCharset,
  [in]           DWORD                  dwFlags,
  [in]           int                    iReqWidth,
  [in, optional] SCRIPT_CONTROL         *psControl,
  [in, optional] SCRIPT_STATE           *psState,
  [in, optional] const int              *piDx,
  [in, optional] SCRIPT_TABDEF          *pTabdef,
  [in]           const BYTE             *pbInClass,
  [out]          SCRIPT_STRING_ANALYSIS *pssa
);

Parameter

[in] hdc

Menangani konteks perangkat. Jika dwFlags diatur ke SSA_GLYPHS, handel konteks perangkat diperlukan. Jika dwFlags diatur ke SSA_BREAK, handel konteks perangkat bersifat opsional. Jika handel konteks perangkat disediakan, fungsi memeriksa font saat ini dalam konteks perangkat. Jika font saat ini adalah font simbolis, fungsi memperlakukan string karakter sebagai satu item SCRIPT_UNDEFINED netral.

[in] pString

Arahkan ke string untuk dianalisis. String harus memiliki setidaknya satu karakter. Ini bisa berupa string Unicode atau menggunakan set karakter dari halaman kode Ansi Windows, seperti yang ditentukan oleh parameter iCharset .

[in] cString

Panjang string yang akan dianalisis. Panjangnya diukur dalam karakter untuk string ANSI atau karakter lebar untuk string Unicode. Panjangnya harus minimal 1.

[in] cGlyphs

Ukuran buffer glyph, dalam nilai WORD. Ukuran ini diperlukan. Ukuran yang disarankan adalah (1.5 * cString + 16).

[in] iCharset

Deskriptor set karakter. Jika string input adalah string ANSI, deskriptor ini diatur ke pengidentifikasi kumpulan karakter. Jika string adalah string Unicode, deskriptor ini diatur ke -1.

Pengidentifikasi set karakter berikut didefinisikan:

[in] dwFlags

Bendera yang menunjukkan analisis yang diperlukan. Parameter ini dapat memiliki salah satu nilai yang tercantum dalam tabel berikut.

Nilai	Makna
SSA_BREAK	Ambil bendera pemisah, yaitu karakter dan penghentian kata.
SSA_CLIP	Klip string di iReqWidth.
SSA_DZWG	Berikan glyph representasi untuk karakter kontrol.
SSA_FALLBACK	Gunakan font fallback.
SSA_FIT	Membenarkan string ke iReqWidth.
SSA_GCP	Ambil glyph dan pwLogClust yang hilang dengan konvensi GetCharacterPlacement .
SSA_GLYPHS	Hasilkan glyph, posisi, dan atribut.
SSA_HIDEHOTKEY	Hapus "&" pertama dari string yang ditampilkan.
SSA_HOTKEY	Ganti "&" dengan garis bawah pada titik kode berikutnya.
SSA_HOTKEYONLY	Tampilkan garis bawah saja. Pola bit yang dihasilkan mungkin ditampilkan, menggunakan masker XOR, untuk mengalihkan visibilitas garis bawah hotkey tanpa mengganggu teks.
SSA_LINK	Terapkan penautan dan asosiasi font Asia Timur ke teks yang tidak lengkap.
SSA_METAFILE	Tulis item dengan panggilan ExtTextOutW , bukan dengan glyph.
SSA_PASSWORD	String input duplikat yang berisi waktu cString karakter tunggal.
SSA_RTL	Gunakan penyematan dasar tingkat 1.
SSA_TAB	Perluas tab.

[in] iReqWidth

Lebar diperlukan untuk pengepasan atau pengklipan.

[in, optional] psControl

Penunjuk ke struktur SCRIPT_CONTROL . Aplikasi dapat mengatur parameter ini ke NULL untuk menunjukkan bahwa semua anggota SCRIPT_CONTROL diatur ke 0.

[in, optional] psState

Penunjuk ke struktur SCRIPT_STATE . Aplikasi dapat mengatur parameter ini ke NULL untuk menunjukkan bahwa semua anggota SCRIPT_STATE diatur ke 0. Anggota uBidiLeveldari SCRIPT_STATE diabaikan. Nilai yang digunakan berasal dari bendera SSA_RTL dalam kombinasi dengan tata letak konteks perangkat.

[in, optional] piDx

Penunjuk ke array dx logis yang diminta.

[in, optional] pTabdef

Penunjuk ke struktur SCRIPT_TABDEF . Nilai ini hanya diperlukan jika dwFlags diatur ke SSA_TAB.

[in] pbInClass

Penunjuk ke nilai BYTE yang menunjukkan klasifikasi karakter GetCharacterPlacement .

[out] pssa

Penunjuk ke buffer tempat fungsi ini mengambil struktur SCRIPT_STRING_ANALYSIS . Struktur ini dialokasikan secara dinamis pada pengembalian yang berhasil dari fungsi.

Nilai kembali

Mengembalikan S_OK jika berhasil. Fungsi mengembalikan nilai HRESULT bukan nol jika tidak berhasil.

Pengembalian kesalahan meliputi:

E_INVALIDARG. Parameter yang tidak valid ditemukan.
USP_E_SCRIPT_NOT_IN_FONT. SSA_FALLBACK belum ditentukan, atau font fallback standar hilang.

Fungsi ini juga dapat mengembalikan kesalahan sistem yang dikonversi ke jenis HRESULT. Contohnya adalah kesalahan yang dikembalikan karena kurangnya memori atau panggilan GDI menggunakan konteks perangkat.

Keterangan

Penggunaan fungsi ini adalah langkah pertama dalam menangani string teks biasa. String semacam itu hanya memiliki satu font, satu gaya, satu ukuran, satu warna, dan sebagainya. ScriptStringAnalyse mengalokasikan buffer sementara untuk analisis item, glyph, lebar lanjutan, dan sejenisnya. Kemudian secara otomatis menjalankan ScriptItemize, ScriptShape, ScriptPlace, dan ScriptBreak. Hasilnya tersedia melalui semua fungsi ScriptString* lainnya.

Pada pengembalian yang berhasil dari fungsi ini, pssa menunjukkan struktur yang dialokasikan secara dinamis bahwa aplikasi dapat meneruskan secara berturut-turut ke fungsi ScriptString* lainnya. Aplikasi pada akhirnya harus membebaskan struktur dengan memanggil ScriptStringFree.

Meskipun fungsionalitas ScriptStringAnalyse dapat diimplementasikan dengan panggilan langsung ke fungsi lain, penggunaan fungsi itu sendiri secara drastis mengurangi jumlah kode yang diperlukan dalam aplikasi untuk penanganan teks biasa.

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 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	usp10.h
Pustaka	Usp10.lib
DLL	Usp10.dll
Redistribusi	Internet Explorer 5 atau yang lebih baru pada Windows Me/98/95