Funzione DrawText (winuser.h)

Articolo
03/13/2024

La funzione DrawText disegna testo formattato nel rettangolo specificato. Formatta il testo in base al metodo specificato (espansione di schede, giustificazione di caratteri, righe di interruzione e così via).

Per specificare opzioni di formattazione aggiuntive, utilizzare la funzione DrawTextEx .

Sintassi

int DrawText(
  [in]      HDC     hdc,
  [in, out] LPCTSTR lpchText,
  [in]      int     cchText,
  [in, out] LPRECT  lprc,
  [in]      UINT    format
);

Parametri

[in] hdc

Handle per il contesto del dispositivo.

[in, out] lpchText

Puntatore alla stringa che specifica il testo da disegnare. Se il parametro nCount è -1, la stringa deve essere con terminazione Null.

Se uFormat include DT_MODIFYSTRING, la funzione potrebbe aggiungere fino a quattro caratteri aggiuntivi a questa stringa. Il buffer contenente la stringa deve essere sufficientemente grande per contenere questi caratteri aggiuntivi.

[in] cchText

Lunghezza, espressa in caratteri, della stringa. Se nCount è -1, si presuppone che il parametro lpchText sia un puntatore a una stringa con terminazione Null e DrawText calcola automaticamente il conteggio dei caratteri.

[in, out] lprc

Puntatore a una struttura RECT che contiene il rettangolo (in coordinate logiche) in cui deve essere formattato il testo.

[in] format

Metodo di formattazione del testo. Questo parametro può essere uno o più dei valori seguenti.

Valore	Significato
DT_BOTTOM	Giustifica il testo nella parte inferiore del rettangolo. Questo valore viene usato solo con il valore DT_SINGLELINE.
DT_CALCRECT	Determina la larghezza e l'altezza del rettangolo. Se sono presenti più righe di testo, DrawText utilizza la larghezza del rettangolo a cui punta il parametro lpRect ed estende la base del rettangolo per associare l'ultima riga di testo. Se la parola più grande è più ampia del rettangolo, la larghezza viene espansa. Se il testo è minore della larghezza del rettangolo, la larghezza viene ridotta. Se è presente una sola riga di testo, DrawText modifica il lato destro del rettangolo in modo che limiti l'ultimo carattere nella riga. In entrambi i casi , DrawText restituisce l'altezza del testo formattato ma non disegna il testo.
DT_CENTER	Centra il testo orizzontalmente nel rettangolo.
DT_EDITCONTROL	Duplica le caratteristiche di visualizzazione del testo di un controllo di modifica su più righe. In particolare, la larghezza media dei caratteri viene calcolata nello stesso modo di un controllo di modifica e la funzione non visualizza un'ultima riga parzialmente visibile.
DT_END_ELLIPSIS	Per il testo visualizzato, se la fine di una stringa non rientra nel rettangolo, viene troncata e vengono aggiunti puntini di sospensione. Se una parola non alla fine della stringa supera i limiti del rettangolo, viene troncata senza puntini di sospensione. La stringa non viene modificata a meno che non venga specificato il flag DT_MODIFYSTRING. Confrontare con DT_PATH_ELLIPSIS e DT_WORD_ELLIPSIS.
DT_EXPANDTABS	Espande i caratteri di tabulazione. Il numero predefinito di caratteri per tabulazione è otto. I valori DT_WORD_ELLIPSIS, DT_PATH_ELLIPSIS e DT_END_ELLIPSIS non possono essere usati con il valore DT_EXPANDTABS.
DT_EXTERNALLEADING	Include l'interlinea esterna del tipo di carattere nell'altezza della riga. In genere, l'inizio esterno non è incluso nell'altezza di una riga di testo.
DT_HIDEPREFIX	Ignora il carattere prefisso e commerciale (&) nel testo. La lettera che segue non verrà sottolineata, ma vengono comunque elaborati altri caratteri di prefisso mnemonico. Esempio: stringa di input: "A&bc&&d" normal: "Abc&d" DT_HIDEPREFIX: "Abc&d" Confrontare con DT_NOPREFIX e DT_PREFIXONLY.
DT_INTERNAL	Utilizza il tipo di carattere di sistema per calcolare le dimensioni del testo.
DT_LEFT	Allinea il testo a sinistra.
DT_MODIFYSTRING	Modifica la stringa specificata in modo che corrisponda al testo visualizzato. Questo valore non ha effetto a meno che non venga specificato DT_END_ELLIPSIS o DT_PATH_ELLIPSIS.
DT_NOCLIP	Disegna senza ritagliare. DrawText è leggermente più veloce quando si usa DT_NOCLIP.
DT_NOFULLWIDTHCHARBREAK	Impedisce un'interruzione di riga in un DBCS (stringa di caratteri a doppio larghezza), in modo che la regola di interruzione della riga sia equivalente alle stringhe SBCS. Ad esempio, questa opzione può essere usata nelle finestre coreane, per una maggiore leggibilità delle etichette delle icone. Questo valore non ha alcun effetto a meno che non venga specificato DT_WORDBREAK.
DT_NOPREFIX	Disattiva l'elaborazione dei caratteri prefisso. In genere , DrawText interpreta il carattere con prefisso mnemonico & come direttiva per evidenziare il carattere che segue e i caratteri con prefisso mnemonico && come direttiva per stampare un singolo &. Specificando DT_NOPREFIX, l'elaborazione viene disattivata. Ad esempio, Esempio: stringa di input: "A&bc&&d" normal: "Abc&d" DT_NOPREFIX: "A&bc&&d" Confrontare con DT_HIDEPREFIX e DT_PREFIXONLY.
DT_PATH_ELLIPSIS	Per il testo visualizzato, sostituisce i caratteri al centro della stringa con i puntini di sospensione in modo che il risultato si adatti al rettangolo specificato. Se la stringa contiene caratteri barra rovesciata (\\), DT_PATH_ELLIPSIS mantiene il più possibile il testo dopo l'ultima barra rovesciata. La stringa non viene modificata a meno che non venga specificato il flag DT_MODIFYSTRING. Confrontare con DT_END_ELLIPSIS e DT_WORD_ELLIPSIS.
DT_PREFIXONLY	Disegna solo una sottolineatura nella posizione del carattere dopo il carattere e commerciale (&) prefisso. Non disegna altri caratteri nella stringa. Ad esempio, Esempio: stringa di input: "A&bc&&d"n normal: "Abc&d" DT_PREFIXONLY: " _ " Confrontare con DT_HIDEPREFIX e DT_NOPREFIX.
DT_RIGHT	Allinea il testo a destra.
DT_RTLREADING	Layout nell'ordine di lettura da destra a sinistra per il testo bidirezionale quando il tipo di carattere selezionato in hdc è un tipo di carattere ebraico o arabo. L'ordine di lettura predefinito per tutto il testo è da sinistra a destra.
DT_SINGLELINE	Visualizza il testo solo in una singola riga. Il ritorno a capo e i feed di riga non interrompono la riga.
DT_TABSTOP	Imposta le tabulazioni. Bit a 15-8 (byte elevato della parola a basso ordine) del parametro uFormat specificare il numero di caratteri per ogni scheda. Il numero predefinito di caratteri per scheda è otto. I valori DT_CALCRECT, DT_EXTERNALLEADING, DT_INTERNAL, DT_NOCLIP e DT_NOPREFIX non possono essere usati con il valore DT_TABSTOP.
DT_TOP	Giustifica il testo nella parte superiore del rettangolo.
DT_VCENTER	Centra il testo verticalmente. Questo valore viene usato solo con il valore DT_SINGLELINE.
DT_WORDBREAK	Interrompe le parole. Le righe vengono interrotte automaticamente tra parole se una parola estenderà il bordo del rettangolo specificato dal parametro lpRect . Una sequenza di feed di ritorno a capo interrompe anche la riga. Se non viene specificato, l'output è in una riga.
DT_WORD_ELLIPSIS	Tronca qualsiasi parola che non si adatta al rettangolo e aggiunge puntini di sospensione. Confrontare con DT_END_ELLIPSIS e DT_PATH_ELLIPSIS.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è l'altezza del testo nelle unità logiche. Se viene specificato DT_VCENTER o DT_BOTTOM, il valore restituito è l'offset dalla lpRect->top parte inferiore del testo disegnato.

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

Commenti

La funzione DrawText usa il tipo di carattere selezionato del contesto del dispositivo, il colore del testo e il colore di sfondo per disegnare il testo. A meno che non venga usato il formato DT_NOCLIP, DrawText ritaglia il testo in modo che non venga visualizzato all'esterno del rettangolo specificato. Si noti che il testo con sovraccarico significativo può essere ritagliato, ad esempio un valore "W" iniziale nella stringa di testo o nel testo in corsivo. Si presuppone che tutte le formattazioni abbiano più righe a meno che non sia specificato il formato DT_SINGLELINE.

Se il tipo di carattere selezionato è troppo grande per il rettangolo specificato, la funzione DrawText non tenta di sostituire un carattere più piccolo.

La modalità di allineamento del testo per il contesto del dispositivo deve includere i flag di TA_LEFT, TA_TOP e TA_NOUPDATECP.

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	winuser.h (include Windows.h)
Libreria	User32.lib
DLL	User32.dll
Set di API	ext-ms-win-ntuser-misc-l1-1-0 (introdotto in Windows 8)