Funzione ExtTextOutA (wingdi.h)

Articolo
03/04/2024

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

Sintassi

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

Parametri

[in] hdc

Handle nel contesto del dispositivo.

[in] x

Coordinata x, nelle coordinate logiche, del punto di riferimento usato per posizionare la stringa.

[in] y

Coordinata y, in coordinate logiche, del punto di riferimento usato 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 sul 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 vettore 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 la stringa viene considerata 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, il metafile deve essere riprodotto usando lo stesso tipo di carattere. Per ExtTextOutA, gli indici glifi non vengono salvati.
ETO_IGNORELANGUAGE	Riservato per l'utilizzo nel sistema. Se un'applicazione imposta questo flag, perde il supporto di 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 usato per riempire il rettangolo.
ETO_PDY	Quando viene impostato, la matrice puntata da 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 carattere.
ETO_RTLREADING	Edizione del linguaggio Middle East di Windows: Se questo valore viene specificato e viene selezionato un carattere ebraico o arabo nel contesto del dispositivo, la stringa viene restituita usando l'ordine di lettura da destra a sinistra. Se questo valore non è specificato, la stringa viene restituita in ordine sinistro a destra. Lo stesso effetto può essere ottenuto impostando il valore TA_RTLREADING in SetTextAlign. Questo valore viene mantenuto per 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 tutte le elaborazioni del linguaggio siano state completate, la funzione ignora il flag di 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. La stringa non deve essere terminata zero, poiché cbCount specifica la lunghezza della stringa.

[in] c

Lunghezza della stringa puntata da lpString.

Questo valore potrebbe non superare il 8192.

[in] lpDx

Puntatore a una matrice facoltativa di valori che indicano la distanza tra le origini delle celle di caratteri adiacenti. Ad esempio, le unità logiche lpDx[i] separano le origini della cella carattere i e della cella carattere 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.

Commenti

Le impostazioni di allineamento del testo correnti per il contesto del dispositivo specificato determinano come viene usato il punto di riferimento 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 sarà sul bordo inferiore del rettangolo di selezione.
TA_TOP	Il punto di riferimento sarà sul bordo superiore del rettangolo di selezione.
TA_CENTER	Il punto di riferimento verrà allineato orizzontalmente al centro del rettangolo di selezione.
TA_LEFT	Il punto di riferimento sarà sul bordo sinistro del rettangolo di selezione.
TA_RIGHT	Il punto di riferimento sarà sul bordo destro del rettangolo di selezione.
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 del testo.
TA_RTLREADING	Edizione del linguaggio Middle East di Windows: Il testo viene disposto a destra per sinistra, anziché all'ordine di lettura predefinito a destra. Ciò si applica 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 del testo. La posizione corrente viene usata come punto di riferimento.

Se il parametro lpDx è NULL, la funzione ExtTextOut usa la spaziatura predefinita tra i caratteri. Le origini della cella di caratteri e il contenuto della matrice a cui punta il parametro lpDx vengono specificati nelle unità logiche. Un'origine della cella di caratteri è definita come 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 chiamate ExtTextOut successive.

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 nelle voci lpDx tra il byte lead e il byte finale, purché la somma dei due byte venga aggiunta fino al dx desiderato. Per i caratteri DBCS con la versione Unicode di ExtTextOut, ogni glifo Unicode ottiene una singola voce pdx .

Nota, i valori 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, causando il fallback del tipo di carattere. Il flag ETO_IGNORELANGUAGE inibirà questo comportamento e non deve essere passato.

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

Suggerimento

ExtTextOut è fortemente consigliato su PolyTextOut per lo sviluppo moderno grazie alla capacità di gestire la visualizzazione di linguaggi diversi.

Esempio

Per un esempio, vedere "Impostazione dei tipi di carattere per Menu-Item stringhe di testo" in Uso dei 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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

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	wingdi.h (include Windows.h)
Libreria	Gdi32.lib
DLL	Gdi32.dll