ExtCreatePen-Funktion (wingdi.h)

Artikel
08/27/2023

Die ExtCreatePen-Funktion erstellt einen logischen kosmetischen oder geometrischen Stift mit den angegebenen Format-, Breiten- und Pinselattributen.

Syntax

HPEN ExtCreatePen(
  [in] DWORD          iPenStyle,
  [in] DWORD          cWidth,
  [in] const LOGBRUSH *plbrush,
  [in] DWORD          cStyle,
  [in] const DWORD    *pstyle
);

Parameter

[in] iPenStyle

Eine Kombination aus Typ-, Stil-, Endcap- und Joinattributen. Die Werte aus jeder Kategorie werden mithilfe des bitweisen OR-Operators ( | ) kombiniert.

Der Stifttyp kann einer der folgenden Werte sein.

Wert	Bedeutung
PS_GEOMETRIC	Der Stift ist geometrisch.
PS_COSMETIC	Der Stift ist kosmetisch.

Der Stiftstil kann einer der folgenden Werte sein.

Wert	Bedeutung
PS_ALTERNATE	Der Stift legt jedes andere Pixel fest. (Dieser Stil gilt nur für kosmetische Stifte.)
PS_SOLID	Der Stift ist einfarbig.
PS_DASH	Der Stift ist gestrichelt.
PS_DOT	Der Stift ist gepunktet.
PS_DASHDOT	Der Stift hat abwechselnd Bindestriche und Punkte.
PS_DASHDOTDOT	Der Stift hat abwechselnd Bindestriche und doppelte Punkte.
PS_NULL	Der Stift ist unsichtbar.
PS_USERSTYLE	Der Stift verwendet ein vom Benutzer bereitgestelltes Formatierungsarray.
PS_INSIDEFRAME	Der Stift ist einfarbig. Wenn dieser Stift in einer beliebigen GDI-Zeichenfunktion verwendet wird, die ein umgebendes Rechteck verwendet, werden die Dimensionen der Figur verkleinert, sodass sie vollständig in das umgebende Rechteck passt, wobei die Breite des Stifts berücksichtigt wird. Dies gilt nur für geometrische Stifte.

Die Endkappe wird nur für geometrische Stifte angegeben. Die Endkappe kann einer der folgenden Werte sein.

Wert	Bedeutung
PS_ENDCAP_ROUND	Endkappen sind rund.
PS_ENDCAP_SQUARE	Endkappen sind quadratisch.
PS_ENDCAP_FLAT	Endkappen sind flach.

Die Verknüpfung wird nur für geometrische Stifte angegeben. Der Join kann einer der folgenden Werte sein.

Wert	Bedeutung
PS_JOIN_BEVEL	Joins sind abgeschrägt.
PS_JOIN_MITER	Joins werden gemildet, wenn sie sich innerhalb des aktuellen Grenzwerts befinden, der von der SetMiterLimit-Funktion festgelegt wurde. Wenn dieser Grenzwert überschritten wird, wird die Verknüpfung abgeschrägt.
PS_JOIN_ROUND	Joins sind rund.

[in] cWidth

Die Breite des Stifts. Wenn der dwPenStyle-Parameter PS_GEOMETRIC ist, wird die Breite in logischen Einheiten angegeben. Wenn dwPenStyle PS_COSMETIC ist, muss die Breite auf 1 festgelegt werden.

[in] plbrush

Ein Zeiger auf eine LOGBRUSH-Struktur . Wenn dwPenStyle PS_COSMETIC ist, gibt das lbColor-Element die Farbe des Stifts an, und das lpStyle-Element muss auf BS_SOLID festgelegt werden. Wenn dwPenStyle PS_GEOMETRIC ist, müssen alle Member verwendet werden, um die Pinselattribute des Stifts anzugeben.

[in] cStyle

Die Länge des lpStyle-Arrays in DWORD-Einheiten. Dieser Wert muss null sein, wenn dwPenStyle nicht PS_USERSTYLE ist.

Die Formatanzahl ist auf 16 begrenzt.

[in] pstyle

Ein Zeiger auf ein Array. Der erste Wert gibt die Länge des ersten Bindestrichs in einem benutzerdefinierten Stil an, der zweite Wert gibt die Länge des ersten Leerzeichens an usw. Dieser Zeiger muss NULL sein, wenn dwPenStyle nicht PS_USERSTYLE ist.

Wenn das lpStyle-Array während der Linienzeichnung überschritten wird, wird der Zeiger auf den Anfang des Arrays zurückgesetzt. Wenn dies geschieht und dwStyleCount eine gerade Zahl ist, wiederholt sich das Muster von Bindestrichen und Leerzeichen. Wenn dwStyleCount jedoch ungerade ist, wird das Muster umgekehrt, wenn der Zeiger zurückgesetzt wird. Das erste Element von lpStyle verweist nun auf Leerzeichen, das zweite auf Bindestriche usw.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle, das einen logischen Stift identifiziert.

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

Hinweise

Ein geometrischer Stift kann eine beliebige Breite aufweisen und jedes der Attribute eines Pinsels aufweisen, z. B. Dither und Muster. Ein kosmetischer Stift kann nur ein einzelnes Pixel breit sein und muss eine einfarbige Farbe sein, aber kosmetische Stifte sind im Allgemeinen schneller als geometrische Stifte.

Die Breite eines geometrischen Stifts wird immer in Welteinheiten angegeben. Die Breite eines kosmetischen Stifts ist immer 1.

Endkappen und Verknüpfungen werden nur für geometrische Stifte angegeben.

Nachdem eine Anwendung einen logischen Stift erstellt hat, kann sie diesen Stift in einem Gerätekontext auswählen, indem sie die SelectObject-Funktion aufruft . Nachdem ein Stift in einem Gerätekontext ausgewählt wurde, kann er zum Zeichnen von Linien und Kurven verwendet werden.

Wenn dwPenStyle PS_COSMETIC und PS_USERSTYLE ist, geben die Einträge im lpStyle-Array längen von Bindestrichen und Leerzeichen in Formateinheiten an. Eine Stileinheit wird durch das Gerät definiert, auf dem der Stift zum Zeichnen einer Linie verwendet wird.

Wenn dwPenStyle PS_GEOMETRIC und PS_USERSTYLE ist, geben die Einträge im lpStyle-Array längen von Bindestrichen und Leerzeichen in logischen Einheiten an.

Wenn dwPenStyle PS_ALTERNATE ist, wird die Formatvorlage ignoriert, und jedes andere Pixel wird festgelegt.

Wenn das lbStyle-Element der LOGBRUSH-Struktur , auf die von lplb verwiesen wird, BS_PATTERN ist, kann die Bitmap, auf die das lbHatch-Element dieser Struktur verweist, kein DIB-Abschnitt sein. Ein DIB-Abschnitt ist eine Bitmap, die von CreateDIBSection erstellt wird. Wenn es sich bei dieser Bitmap um einen DIB-Abschnitt handelt, schlägt die ExtCreatePen-Funktion fehl.

Wenn eine Anwendung keinen angegebenen Stift mehr benötigt, sollte sie die DeleteObject-Funktion aufrufen, um den Stift zu löschen.

ICM: Bei der Stifterstellung wird keine Farbverwaltung durchgeführt. Die Farbverwaltung wird jedoch ausgeführt, wenn der Stift in einen ICM-fähigen Gerätekontext ausgewählt wird.

Beispiele

Ein Beispiel finden Sie unter Verwenden von Stiften.

Anforderungen


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