CreatePen-Funktion (wingdi.h)

Artikel
03/04/2024

Die CreatePen-Funktion erstellt einen logischen Stift mit der angegebenen Formatvorlage, Breite und Farbe. Der Stift kann anschließend in einem Gerätekontext ausgewählt und zum Zeichnen von Linien und Kurven verwendet werden.

Syntax

HPEN CreatePen(
  [in] int      iStyle,
  [in] int      cWidth,
  [in] COLORREF color
);

Parameter

[in] iStyle

Der Stiftstil. Es kann sich um einen der folgenden Werte handeln.

Wert	Bedeutung
PS_SOLID	Der Stift ist einfarbig.
PS_DASH	Der Stift ist gestrichelt. Diese Formatvorlage ist nur gültig, wenn die Stiftbreite in Geräteeinheiten ein oder weniger beträgt.
PS_DOT	Der Stift ist gepunktet. Diese Formatvorlage ist nur gültig, wenn die Stiftbreite in Geräteeinheiten ein oder weniger beträgt.
PS_DASHDOT	Der Stift hat abwechselnd Bindestriche und Punkte. Diese Formatvorlage ist nur gültig, wenn die Stiftbreite in Geräteeinheiten ein oder weniger beträgt.
PS_DASHDOTDOT	Der Stift hat abwechselnd Bindestriche und doppelte Punkte. Diese Formatvorlage ist nur gültig, wenn die Stiftbreite in Geräteeinheiten ein oder weniger beträgt.
PS_NULL	Der Stift ist unsichtbar.
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.

[in] cWidth

Die Breite des Stifts in logischen Einheiten. Wenn nWidth null ist, ist der Stift ein einzelnes Pixel breit, unabhängig von der aktuellen Transformation.

CreatePen gibt einen Stift mit der angegebenen Breite, aber mit der PS_SOLID-Formatvorlage zurück, wenn Sie eine Breite größer als 1 für die folgenden Formatvorlagen angeben: PS_DASH, PS_DOT, PS_DASHDOT, PS_DASHDOTDOT.

[in] color

Ein Farbverweis für die Stiftfarbe. Um eine COLORREF-Struktur zu generieren, verwenden Sie das RGB-Makro .

Rückgabewert

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

Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL.

Hinweise

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 der durch den nWidth-Parameter angegebene Wert 0 ist, ist eine mit dem erstellten Stift gezeichnete Linie unabhängig von der aktuellen Transformation immer ein einzelnes Pixel breit.

Wenn der von nWidth angegebene Wert größer als 1 ist, muss der fnPenStyle-Parameter PS_NULL, PS_SOLID oder PS_INSIDEFRAME sein.

Wenn der von nWidth angegebene Wert größer als 1 ist und fnPenStyle PS_INSIDEFRAME ist, wird die dem Stift zugeordnete Linie innerhalb des Rahmens aller Grundtypen mit Ausnahme von Polygonen und Polylinien gezeichnet.

Wenn der durch nWidth angegebene Wert größer als 1 ist, fnPenStyle PS_INSIDEFRAME ist und die vom crColor-Parameter angegebene Farbe nicht mit einem der Einträge in der logischen Palette übereinstimmt, zeichnet das System Linien mit einer ditherierten Farbe. Dithered-Farben sind mit vollfarbigen Stiften nicht verfügbar.

Wenn Sie einen iStyle-Parameter von PS_DASH, PS_DOT, PS_DASHDOT oder PS_DASHDOTDOT verwenden, um die Lücken zwischen den Bindestrichen oder Punkten transparent zu machen, verwenden Sie SetBkMode , um den Modus auf TRANSPARENT festzulegen.

Wenn Sie den Stift nicht mehr benötigen, rufen Sie die DeleteObject-Funktion auf, um ihn zu löschen.

ICM: Bei der Erstellung 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 Erstellen farbiger Stifte und Pinsel.

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 (einschließlich Windows.h)
Bibliothek	Gdi32.lib
DLL	Gdi32.dll