Funzione ExtTextOutW (wingdi.h)

Articolo
11/20/2024

La funzione exttextout disegna testo utilizzando il tipo di carattere, il colore di sfondo e il colore del testo attualmente selezionati. Facoltativamente, è possibile specificare le dimensioni da utilizzare per ritagliare, opaquing o entrambi.

Sintassi

BOOL ExtTextOutW(
  [in] HDC        hdc,
  [in] int        x,
  [in] int        y,
  [in] UINT       options,
  [in] const RECT *lprect,
  [in] LPCWSTR    lpString,
  [in] UINT       c,
  [in] const INT  *lpDx
);

Parametri

[in] hdc

Handle per il contesto del dispositivo.

[in] x

Coordinata x, in coordinate logiche, del punto di riferimento utilizzato per posizionare la stringa.

[in] y

Coordinata y, in coordinate logiche, del punto di riferimento utilizzato per posizionare la stringa.

[in] options

Specifica come usare il rettangolo definito dall'applicazione. Questo parametro può essere uno o più dei valori seguenti.

Valore	Significato
ETO_CLIPPED	Il testo verrà ritagliato nel rettangolo.
ETO_GLYPH_INDEX	La matrice lpString fa riferimento a una matrice restituita da GetCharacterPlacement e deve essere analizzata direttamente da GDI perché non è necessaria alcuna ulteriore elaborazione specifica del linguaggio. L'indicizzazione del glifo si applica solo ai tipi di carattere TrueType, ma il flag può essere usato per i tipi di carattere bitmap e vettoriali per indicare che non è necessaria alcuna ulteriore elaborazione del linguaggio e GDI deve elaborare direttamente la stringa. Si noti che tutti gli indici glifi sono valori a 16 bit anche se si presuppone che la stringa sia una matrice di valori a 8 bit per i tipi di carattere raster. Per ExtTextOutW, gli indici glifi vengono salvati in un metafile. Tuttavia, per visualizzare i caratteri corretti, è necessario riprodurre il metafile usando lo stesso tipo di carattere. Per ExtTextOutA, gli indici del glifo non vengono salvati.
ETO_IGNORELANGUAGE	Riservato per l'uso del sistema. Se un'applicazione imposta questo flag, perde il supporto per lo scripting internazionale e in alcuni casi potrebbe non visualizzare alcun testo.
ETO_NUMERICSLATIN	Per visualizzare i numeri, usare cifre europee.
ETO_NUMERICSLOCAL	Per visualizzare i numeri, usare le cifre appropriate per le impostazioni locali.
ETO_OPAQUE	Il colore di sfondo corrente deve essere utilizzato per riempire il rettangolo.
ETO_PDY	Quando questa opzione è impostata, la matrice a cui punta lpDx contiene coppie di valori. Il primo valore di ogni coppia è, come di consueto, la distanza tra le origini delle celle di caratteri adiacenti, ma il secondo valore è lo spostamento lungo la direzione verticale del tipo di carattere.
ETO_RTLREADING	edizione della lingua del Medio Oriente di Windows: Se questo valore è specificato e nel contesto del dispositivo è selezionato un tipo di carattere ebraico o arabo, la stringa viene restituita usando l'ordine di lettura da destra a sinistra. Se questo valore non viene specificato, la stringa viene restituita in ordine da sinistra a destra. Lo stesso effetto può essere ottenuto impostando il valore di TA_RTLREADING in SetTextAlign. Questo valore viene mantenuto per garantire la compatibilità con le versioni precedenti.

I valori ETO_GLYPH_INDEX e ETO_RTLREADING non possono essere usati insieme. Poiché ETO_GLYPH_INDEX implica che tutta l'elaborazione del linguaggio è stata completata, la funzione ignora il flag ETO_RTLREADING se specificato.

[in] lprect

Puntatore a una struttura RECT facoltativa che specifica le dimensioni, nelle coordinate logiche, di un rettangolo utilizzato per ritagliare, opaquing o entrambi.

[in] lpString

Puntatore a una stringa che specifica il testo da disegnare. Non è necessario che la stringa sia con terminazione zero, perché cbCount specifica la lunghezza della stringa.

[in] c

Lunghezza della stringa a cui punta lpString.

Questo valore potrebbe non superare l'8192.

[in] lpDx

Puntatore a una matrice facoltativa di valori che indica la distanza tra le origini delle celle di caratteri adiacenti. Ad esempio, le unità logiche lpDx[i] separano le origini della cella di caratteri i e cella di caratteri i + 1.

Valore restituito

Se la stringa viene disegnata, il valore restituito è diverso da zero. Tuttavia, se la versione ANSI di ExtTextOut viene chiamata con ETO_GLYPH_INDEX, la funzione restituisce TRUE anche se la funzione non esegue alcuna operazione.

Se la funzione ha esito negativo, il valore restituito è zero.

Osservazioni

Le impostazioni di allineamento del testo correnti per il contesto di dispositivo specificato determinano il modo in cui il punto di riferimento viene usato per posizionare il testo. Le impostazioni di allineamento del testo vengono recuperate chiamando la funzione GetTextAlign. Le impostazioni di allineamento del testo vengono modificate chiamando la funzione SetTextAlign. È possibile usare i valori seguenti per l'allineamento del testo. È possibile scegliere un solo flag da quelli che influiscono sull'allineamento orizzontale e verticale. Inoltre, è possibile scegliere solo uno dei due flag che modificano la posizione corrente.

Termine	Descrizione
TA_BASELINE	Il punto di riferimento sarà sulla riga di base del testo.
TA_BOTTOM	Il punto di riferimento si troverà sul bordo inferiore del rettangolo di delimitazione.
TA_TOP	Il punto di riferimento si troverà sul bordo superiore del rettangolo di delimitazione.
TA_CENTER	Il punto di riferimento verrà allineato orizzontalmente al centro del rettangolo di delimitazione.
TA_LEFT	Il punto di riferimento sarà sul bordo sinistro del rettangolo di delimitazione.
TA_RIGHT	Il punto di riferimento sarà sul bordo destro del rettangolo di delimitazione.
TA_NOUPDATECP	La posizione corrente non viene aggiornata dopo ogni chiamata di output di testo. Il punto di riferimento viene passato alla funzione di output di testo.
TA_RTLREADING	edizione della lingua del Medio Oriente di Windows: Il testo è disposto da destra a sinistra, anziché dall'ordine predefinito da sinistra a destra. Questo vale solo quando il tipo di carattere selezionato nel contesto del dispositivo è ebraico o arabo.
TA_UPDATECP	La posizione corrente viene aggiornata dopo ogni chiamata di output di testo. La posizione corrente viene utilizzata come punto di riferimento.

Se il parametro lpDx è NULL, la funzione ExtTextOut utilizza la spaziatura predefinita tra i caratteri. Le origini delle celle di caratteri e il contenuto della matrice a cui punta il parametro lpDx vengono specificati in unità logiche. Un'origine della cella di caratteri è definita come l'angolo superiore sinistro della cella di caratteri.

Per impostazione predefinita, la posizione corrente non viene usata o aggiornata da questa funzione. Tuttavia, un'applicazione può chiamare la funzione SetTextAlign con il parametro fMode impostato su TA_UPDATECP per consentire al sistema di usare e aggiornare la posizione corrente ogni volta che l'applicazione chiama ExtTextOut per un contesto di dispositivo specificato. Quando questo flag è impostato, il sistema ignora i parametri X e Y nelle successive chiamate ExtTextOut.

Per la versione ANSI di ExtTextOut, la matrice lpDx ha lo stesso numero di valori INT presenti in lpString. Per i caratteri DBCS, è possibile suddividere il dx nella lpDx voci tra il byte iniziale e il byte finale, purché la somma dei due byte aggiunga fino al dx desiderato. Per i caratteri DBCS con la versione Unicode di ExtTextOut, ogni glifo Unicode ottiene una singola voce pdx.

Si noti che i valori di alpDx di GetTextExtentExPoint non sono uguali ai valori lpDx per ExtTextOut. Per usare i valori alpDx in lpDx, è prima necessario elaborarli.

ExtTextOut userà Uniscribe quando necessario, con conseguente fallback del tipo di carattere. Il flag ETO_IGNORELANGUAGE inibirà questo comportamento e non deve essere passato.

Inoltre, ExtTextOut eseguirà l'invio in batch interno delle chiamate prima della transizione alla modalità kernel, riducendo alcuni dei problemi di prestazioni quando si pesa l'utilizzo di PolyTextOut rispetto a ExtTextOut.

Mancia

ExtTextOut è consigliabile PolyTextOut per lo sviluppo moderno grazie alla possibilità di gestire la visualizzazione di linguaggi diversi.

Esempi

Per un esempio, vedere "Impostazione dei tipi di carattere per stringhe di testo Menu-Item" in Uso di menu.

Nota

L'intestazione wingdi.h definisce ExtTextOut come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	wingdi.h (include Windows.h)
libreria	Gdi32.lib
dll	Gdi32.dll