GetTextExtentExPointA-Funktion (wingdi.h)

Die GetTextExtentExPoint-Funktion ruft die Anzahl der Zeichen in einer angegebenen Zeichenfolge ab, die in ein angegebenes Leerzeichen passt, und füllt ein Array mit der Textausdehnung für jedes dieser Zeichen aus. (Eine Textausdehnung ist der Abstand zwischen dem Anfang des Leerzeichens und einem Zeichen, das in das Leerzeichen passt.) Diese Informationen sind nützlich für Word-Wrapping-Berechnungen.

Syntax

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

Parameter

[in] hdc

Ein Handle für den Gerätekontext.

[in] lpszString

Ein Zeiger auf die NULL-endende Zeichenfolge, für die Blöcke abgerufen werden sollen.

[in] cchString

Die Anzahl der Zeichen in der Zeichenfolge, auf die der lpszStr-Parameter verweist. Für einen ANSI-Aufruf gibt er die Zeichenfolgenlänge in Bytes und für einen Unicode die Zeichenfolgenlänge in WORDs an. Beachten Sie, dass für die ANSI-Funktion zeichen in SBCS-Codepages jeweils ein Byte verwendet werden, während die meisten Zeichen in DBCS-Codepages zwei Bytes umfassen. für die Unicode-Funktion sind die meisten derzeit definierten Unicode-Zeichen (die in der basic Multilingual Plane (BMP)) ein WORD, während Unicode-Ersatzzeichen zwei WORDs sind.

[in] nMaxExtent

Die maximal zulässige Breite der formatierten Zeichenfolge in logischen Einheiten.

[out] lpnFit

Ein Zeiger auf eine ganze Zahl, die die Anzahl der maximalen Zeichen empfängt, die in das durch den nMaxExtent-Parameter angegebene Leerzeichen passen. Wenn der lpnFit-ParameterNULL ist, wird der nMaxExtent-Parameter ignoriert.

[out] lpnDx

Ein Zeiger auf ein Array von ganzen Zahlen, das partielle Zeichenfolgenausdehnungen empfängt. Jedes Element im Array gibt den Abstand in logischen Einheiten zwischen dem Anfang der Zeichenfolge und einem der Zeichen an, die in das durch den nMaxExtent-Parameter angegebene Leerzeichen passen. Dieses Array muss mindestens so viele Elemente wie vom cchString-Parameter angegebene Zeichen enthalten, da das gesamte Array intern verwendet wird. Die Funktion füllt das Array mit gültigen Blöcken für so viele Zeichen, wie vom lpnFit-Parameter angegeben werden. Alle Werte im rest des Arrays sollten ignoriert werden. Wenn alpDxNULL ist, berechnet die Funktion keine teiligen Zeichenfolgenbreiten.

Bei komplexen Skripts, bei denen eine Sequenz von Zeichen durch eine beliebige Anzahl von Glyphen dargestellt werden kann, stimmen die Werte im alpDx-Array bis zu der durch den lpnFit-Parameter angegebenen Zahl 1:1 mit Codepunkten überein. Auch hier sollten Sie die restlichen Werte im alpDx-Array ignorieren.

[out] lpSize

Ein Zeiger auf eine SIZE-Struktur , die die Dimensionen der Zeichenfolge in logischen Einheiten empfängt. Dieser Parameter darf nicht NULL sein.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null.

Hinweise

Wenn sowohl der lpnFit - als auch der alpDx-ParameterNULL sind, entspricht das Aufrufen der GetTextExtentExPoint-Funktion dem Aufrufen der GetTextExtentPoint-Funktion .

Für die ANSI-Version von GetTextExtentExPoint verfügt das lpDx-Array über die gleiche Anzahl von INT-Werten wie bytes in lpString. Die INT-Werte, die den beiden Bytes eines DBCS-Zeichens entsprechen, sind jeweils die Ausdehnung des gesamten zusammengesetzten Zeichens.

Beachten Sie, dass die alpDx-Werte für GetTextExtentExPoint nicht mit den lpDx-Werten für ExtTextOut identisch sind. Um die alpDx-Werte in lpDx zu verwenden, müssen Sie sie zuerst verarbeiten.

Wenn diese Funktion den Textumfang zurückgibt, wird davon ausgegangen, dass der Text horizontal ist, d. h., dass die Escapement immer 0 ist. Dies gilt sowohl für die horizontalen als auch für die vertikalen Maße des Texts. Selbst wenn Sie eine Schriftart verwenden, die eine Escapeung ungleich null angibt, verwendet diese Funktion nicht den Winkel, während sie den Textumfang berechnet. Die App muss sie explizit konvertieren. Wenn der Grafikmodus jedoch auf GM_ADVANCED festgelegt ist und die Zeichenausrichtung 90 Grad von der Druckausrichtung entfernt ist, folgen die von dieser Funktion zurückgegebenen Werte nicht dieser Regel. Wenn die Zeichenausrichtung und die Druckausrichtung für eine bestimmte Zeichenfolge übereinstimmen, gibt diese Funktion die Dimensionen der Zeichenfolge in der SIZE-Struktur als { cx : 116, cy : 18 } zurück. Wenn die Zeichenausrichtung und die Druckausrichtung für dieselbe Zeichenfolge 90 Grad voneinander entfernt sind, gibt diese Funktion die Dimensionen der Zeichenfolge in der SIZE-Struktur als { cx : 18, cy : 116 } zurück.

Diese Funktion gibt den Umfang jedes aufeinander folgenden Zeichens in einer Zeichenfolge zurück. Wenn diese auf logische Einheiten gerundet werden, erhalten Sie andere Ergebnisse als das, was von GetCharWidth zurückgegeben wird, das die Breite jedes einzelnen Zeichens zurückgibt, das auf logische Einheiten gerundet wird.

Hinweis

Der wingdi.h-Header definiert GetTextExtentExPoint als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	wingdi.h (windows.h einschließen)
Bibliothek	Gdi32.lib
DLL	Gdi32.dll

Weitere Informationen

Schriftart- und Textfunktionen

Übersicht über Schriftarten und Text

GetTextExtentPoint

SIZE