Funzione ScriptStringAnalyse (usp10.h)

Articolo
08/26/2023

Analizza una stringa di testo normale.

Sintassi

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
);

Parametri

[in] hdc

Gestire nel contesto del dispositivo. Se dwFlags è impostato su SSA_GLYPHS, è necessario l'handle del contesto di dispositivo. Se dwFlags è impostato su SSA_BREAK, l'handle del contesto di dispositivo è facoltativo. Se viene fornito l'handle del contesto di dispositivo, la funzione controlla il tipo di carattere corrente nel contesto del dispositivo. Se il tipo di carattere corrente è un tipo di carattere simbolico, la funzione considera la stringa di caratteri come un singolo elemento SCRIPT_UNDEFINED neutro.

[in] pString

Puntatore alla stringa da analizzare. La stringa deve contenere almeno un carattere. Può essere una stringa Unicode o usare il set di caratteri da una tabella codici ANSI di Windows, come specificato dal parametro iCharset .

[in] cString

Lunghezza della stringa da analizzare. La lunghezza viene misurata in caratteri per una stringa ANSI o in caratteri wide per una stringa Unicode. La lunghezza deve essere almeno 1.

[in] cGlyphs

Dimensioni del buffer del glifo, in valori DI WORD. Questa dimensione è obbligatoria. La dimensione consigliata è (1.5 * cString + 16).

[in] iCharset

Descrittore del set di caratteri. Se la stringa di input è una stringa ANSI, questo descrittore viene impostato sull'identificatore del set di caratteri. Se la stringa è una stringa Unicode, questo descrittore viene impostato su -1.

Vengono definiti gli identificatori del set di caratteri seguenti:

[in] dwFlags

Flag che indicano l'analisi necessaria. Questo parametro può avere uno dei valori elencati nella tabella seguente.

Valore	Significato
SSA_BREAK	Recuperare i flag di interruzione, ovvero carattere e parola si arresta.
SSA_CLIP	Ritagliare la stringa in iReqWidth.
SSA_DZWG	Fornire glifi di rappresentazione per i caratteri di controllo.
SSA_FALLBACK	Usare i tipi di carattere di fallback.
SSA_FIT	Giustificare la stringa in iReqWidth.
SSA_GCP	Recuperare glifi mancanti e pwLogClust con le convenzioni GetCharacterPlacement .
SSA_GLYPHS	Generare glifi, posizioni e attributi.
SSA_HIDEHOTKEY	Rimuovere la prima "&" dalla stringa visualizzata.
SSA_HOTKEY	Sostituire "&" con sottolineatura sul punto di codice successivo.
SSA_HOTKEYONLY	Visualizza solo sottolineatura. È possibile visualizzare il modello di bit risultante, usando una maschera XOR, per attivare o disattivare la visibilità della sottolineatura del tasto di scelta rapida senza disturbare il testo.
SSA_LINK	Applicare il collegamento e l'associazione dei tipi di carattere asiatici al testo non complesso.
SSA_METAFILE	Scrivere elementi con chiamate ExtTextOutW , non con glifi.
SSA_PASSWORD	Stringa di input duplicata contenente un singolo carattere cString times.
SSA_RTL	Usare il livello di incorporamento di base 1.
SSA_TAB	Espandere le schede.

[in] iReqWidth

Larghezza necessaria per adattarsi o ritagliare.

[in, optional] psControl

Puntatore a una struttura SCRIPT_CONTROL . L'applicazione può impostare questo parametro su NULL per indicare che tutti i membri SCRIPT_CONTROL sono impostati su 0.

[in, optional] psState

Puntatore a una struttura SCRIPT_STATE . L'applicazione può impostare questo parametro su NULL per indicare che tutti i membri SCRIPT_STATE sono impostati su 0. Il membro uBidiLevel di SCRIPT_STATE viene ignorato. Il valore usato deriva dal flag SSA_RTL in combinazione con il layout del contesto di dispositivo.

[in, optional] piDx

Puntatore alla matrice dx logica richiesta.

[in, optional] pTabdef

Puntatore a una struttura SCRIPT_TABDEF . Questo valore è obbligatorio solo se dwFlags è impostato su SSA_TAB.

[in] pbInClass

Puntatore a un valore BYTE che indica le classificazioni dei caratteri GetCharacterPlacement .

[out] pssa

Puntatore a un buffer in cui questa funzione recupera una struttura SCRIPT_STRING_ANALYSIS . Questa struttura viene allocata dinamicamente in caso di esito positivo della restituzione dalla funzione .

Valore restituito

Restituisce S_OK in caso di esito positivo. Se non ha esito positivo, la funzione restituisce un valore HRESULT diverso da zero.

I valori restituiti dall'errore includono:

E_INVALIDARG. Viene trovato un parametro non valido.
USP_E_SCRIPT_NOT_IN_FONT. SSA_FALLBACK non è stato specificato o manca un tipo di carattere di fallback standard.

La funzione può anche restituire un errore di sistema convertito in un tipo HRESULT. Un esempio è un errore restituito a causa della mancanza di memoria o di una chiamata GDI usando il contesto di dispositivo.

Commenti

L'uso di questa funzione è il primo passaggio per gestire le stringhe di testo normale. Tale stringa ha un solo tipo di carattere, uno stile, una dimensione, un colore e così via. ScriptStringAnalyse alloca buffer temporanei per analisi degli elementi, glifi, larghezze avanzate e simili. Esegue quindi automaticamente ScriptItemize, ScriptShape, ScriptPlace e ScriptBreak. I risultati sono disponibili tramite tutte le altre funzioni ScriptString* .

Al termine della restituzione da questa funzione, pssa indica una struttura allocata dinamicamente che l'applicazione può passare successivamente alle altre funzioni ScriptString* . L'applicazione deve infine liberare la struttura chiamando ScriptStringFree.

Anche se la funzionalità di ScriptStringAnalyse può essere implementata tramite chiamate dirette ad altre funzioni, l'uso della funzione stessa riduce drasticamente la quantità di codice necessaria nell'applicazione per la gestione del testo normale.

Importante A partire da Windows 8: per mantenere la possibilità di eseguire in Windows 7, un modulo che usa Uniscribe deve specificare Usp10.lib prima di gdi32.lib nell'elenco di librerie.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	usp10.h
Libreria	Usp10.lib
DLL	Usp10.dll
Componente ridistribuibile	Internet Explorer 5 o versione successiva in Windows Me/98/95