Funzione GetTextExtentExPointW (wingdi.h)

Articolo
11/20/2024

La funzione GetTextExtentExPoint recupera il numero di caratteri in una stringa specificata che verrà inserita all'interno di uno spazio specificato e riempie una matrice con l'extent di testo per ognuno di questi caratteri. Un extent di testo è la distanza tra l'inizio dello spazio e un carattere che si adatta allo spazio. Queste informazioni sono utili per i calcoli di ritorno a capo automatico.

Sintassi

BOOL GetTextExtentExPointW(
  [in]  HDC     hdc,
  [in]  LPCWSTR lpszString,
  [in]  int     cchString,
  [in]  int     nMaxExtent,
  [out] LPINT   lpnFit,
  [out] LPINT   lpnDx,
  [out] LPSIZE  lpSize
);

Parametri

[in] hdc

Handle per il contesto del dispositivo.

[in] lpszString

Puntatore alla stringa con terminazione Null per cui devono essere recuperati gli extent.

[in] cchString

Numero di caratteri nella stringa a cui punta il parametro lpszStr. Per una chiamata ANSI specifica la lunghezza della stringa in byte e per un unicode specifica la lunghezza della stringa nei word. Si noti che per la funzione ANSI, i caratteri nelle tabelle codici SBCS accettano un byte ciascuno, mentre la maggior parte dei caratteri nelle tabelle codici DBCS accetta due byte; per la funzione Unicode, la maggior parte dei caratteri Unicode attualmente definiti (quelli in Basic Multilingual Plane (BMP)) sono una PAROLA mentre i surrogati Unicode sono due WORD.

[in] nMaxExtent

Larghezza massima consentita, in unità logiche, della stringa formattata.

[out] lpnFit

Puntatore a un numero intero che riceve un conteggio del numero massimo di caratteri che verrà inserito nello spazio specificato dal parametro nMaxExtent. Quando il parametro lpnFit è NULL, il parametro nMaxExtent viene ignorato.

[out] lpnDx

Puntatore a una matrice di numeri interi che riceve extent di stringa parziali. Ogni elemento della matrice assegna la distanza, in unità logiche, tra l'inizio della stringa e uno dei caratteri che si inserisce nello spazio specificato dal parametro nMaxExtent. Questa matrice deve contenere almeno il numero di caratteri specificati dal parametro cchString perché l'intera matrice viene usata internamente. La funzione riempie la matrice con extent validi per il numero di caratteri specificato dal parametro lpnFit. Tutti i valori nel resto della matrice devono essere ignorati. Se alpDx è NULL, la funzione non calcola le larghezze parziali delle stringhe.

Per gli script complessi, in cui una sequenza di caratteri può essere rappresentata da un numero qualsiasi di glifi, i valori nella matrice alpDx fino al numero specificato dal parametro lpnFit corrispondono uno a uno con i punti di codice. Anche in questo caso, è necessario ignorare il resto dei valori nella matrice alpDx.

[out] lpSize

Puntatore a una struttura SIZE che riceve le dimensioni della stringa, in unità logiche. Questo parametro non può essere NULL.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

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

Osservazioni

Se entrambi i parametri lpnFit e alpDx sono null, la chiamata alla funzione GetTextExtentExPoint equivale a chiamare la funzione GetTextExtentPoint.

Per la versione ANSI di GetTextExtentExPoint, la matrice lpDx ha lo stesso numero di valori INT presenti in lpString. I valori INT che corrispondono ai due byte di un carattere DBCS sono ognuno l'extent dell'intero carattere composito.

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

Quando questa funzione restituisce l'extent di testo, presuppone che il testo sia orizzontale, ovvero che l'escape sia sempre 0. Questo vale sia per le misurazioni orizzontali che verticali del testo. Anche se si usa un tipo di carattere che specifica un carattere di escape diverso da zero, questa funzione non usa l'angolo mentre calcola l'extent di testo. L'app deve convertirla in modo esplicito. Tuttavia, quando la modalità grafica è impostata su GM_ADVANCED e l'orientamento del carattere è di 90 gradi dall'orientamento di stampa, i valori restituiti da questa funzione non seguono questa regola. Quando l'orientamento del carattere e l'orientamento di stampa corrispondono a una determinata stringa, questa funzione restituisce le dimensioni della stringa nella struttura SIZE come { cx : 116, cy : 18 }. Quando l'orientamento dei caratteri e l'orientamento di stampa sono di 90 gradi per la stessa stringa, questa funzione restituisce le dimensioni della stringa nella struttura SIZE come { cx : 18, cy : 116 }.

Questa funzione restituisce l'extent di ogni carattere successivo in una stringa. Quando questi vengono arrotondati a unità logiche, si ottengono risultati diversi rispetto a quelli restituiti dalla GetCharWidth, che restituisce la larghezza di ogni singolo carattere arrotondato alle unità logiche.

Nota

L'intestazione wingdi.h definisce GetTextExtentExPoint 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

Vedere anche

funzioni di tipo carattere e testo

panoramica tipi di carattere e testo

GetTextExtentPoint

SIZE

Condividi tramite