CPen-Klasse

  • Artikel

Kapselt einen Stift der Windows GDI (Graphics Device Interface).

Syntax

class CPen : public CGdiObject

Member

Öffentliche Konstruktoren

Name Beschreibung
CPen::CPen Erstellt ein CPen-Objekt.

Öffentliche Methoden

Name Beschreibung
CPen::CreatePen Erstellt einen logischen kosmetischen oder geometrischen Stift mit den angegebenen Stil-, Breiten- und Pinselattributen und fügt ihn an das CPen Objekt an.
CPen::CreatePenIndirect Erstellt einen Stift mit der in einer LOGPEN Struktur angegebenen Formatvorlage, Breite und Farbe und fügt ihn an das CPen Objekt an.
CPen::FromHandle Gibt einen Zeiger auf ein CPen Objekt zurück, wenn ein Windows HPEN angegeben ist.
CPen::GetExtLogPen Ruft eine EXTLOGPEN zugrunde liegende Struktur ab.
CPen::GetLogPen Ruft eine LOGPEN zugrunde liegende Struktur ab.

Öffentliche Operatoren

Name Beschreibung
CPen::operator HPEN Gibt das dem Objekt angefügte CPen Windows-Handle zurück.

Hinweise

Weitere Informationen zur Verwendung CPenfinden Sie unter Graphic Objects.

Vererbungshierarchie

CObject

CGdiObject

CPen

Anforderungen

Headerafxwin.h:

CPen::CPen

Erstellt ein CPen-Objekt.

CPen();

CPen(
    int nPenStyle,
    int nWidth,
    COLORREF crColor);

CPen(
    int nPenStyle,
    int nWidth,
    const LOGBRUSH* pLogBrush,
    int nStyleCount = 0,
    const DWORD* lpStyle = NULL);

Parameter

nPenStyle
Gibt die Stiftart an. Dieser Parameter in der ersten Version des Konstruktors kann einen der folgenden Werte aufweisen:

  • PS_SOLID Erstellt einen einfarbigen Stift.

  • PS_DASH Erstellt einen gestrichelten Stift. Nur gültig, wenn die Stiftbreite 1 oder kleiner ist, in Geräteeinheiten.

  • PS_DOT Erstellt einen gepunkteten Stift. Nur gültig, wenn die Stiftbreite 1 oder kleiner ist, in Geräteeinheiten.

  • PS_DASHDOT Erstellt einen Stift mit abwechselnden Strichen und Punkten. Nur gültig, wenn die Stiftbreite 1 oder kleiner ist, in Geräteeinheiten.

  • PS_DASHDOTDOT Erstellt einen Stift mit abwechselnden Strichen und doppelten Punkten. Nur gültig, wenn die Stiftbreite 1 oder kleiner ist, in Geräteeinheiten.

  • PS_NULL Erstellt einen NULL-Stift.

  • PS_INSIDEFRAMEErstellt einen Stift, der eine Linie innerhalb des Rahmens geschlossener Formen zeichnet, die von den Windows GDI-Ausgabefunktionen erzeugt werden, die ein umgebendes Rechteck angeben (z. B. die EllipseFunktionen , , Rectangle, RoundRectPieund Chord Member). Wenn diese Formatvorlage mit Windows GDI-Ausgabefunktionen verwendet wird, die kein umgebendes Rechteck (z. B. die LineTo Memberfunktion) angeben, wird der Zeichnungsbereich des Stifts nicht durch einen Frame beschränkt.

Die zweite Version des CPen Konstruktors gibt eine Kombination aus Typ-, Stil-, Endbuchstaben- und Verknüpfungsattributen an. Die Werte aus jeder Kategorie sollten mit dem bitweisen Operator "or" (|) kombiniert werden. Der Stifttyp kann einen der folgenden Werte aufweisen:

  • PS_GEOMETRIC Erstellt einen geometrischen Stift.

  • PS_COSMETIC Erstellt einen kosmetischen Stift.

    Die zweite Version des CPen Konstruktors fügt die folgenden Stiftformate für nPenStyle:

  • PS_ALTERNATE Erstellt einen Stift, der jedes andere Pixel festlegt. (Dieser Stil gilt nur für kosmetische Stifte.)

  • PS_USERSTYLE Erstellt einen Stift, der ein vom Benutzer bereitgestelltes Formatierungsarray verwendet.

    Die Endkappe kann einen der folgenden Werte aufweisen:

  • PS_ENDCAP_ROUND Endkappen sind rund.

  • PS_ENDCAP_SQUARE Endkappen sind quadratisch.

  • PS_ENDCAP_FLAT Endkappen sind flach.

    Bei der Verknüpfung kann es sich um einen der folgenden Werte handeln:

  • PS_JOIN_BEVEL Verknüpfungen sind abgeschrägt.

  • PS_JOIN_MITER Verknüpfungen werden gemildert, wenn sie sich innerhalb des aktuellen Grenzwerts befinden, der von der SetMiterLimit Funktion festgelegt wird. Wenn die Verknüpfung diesen Grenzwert überschreitet, wird sie abgeschrägt.

  • PS_JOIN_ROUND Verknüpfungen sind rund.

nWidth
Gibt die Breite des Stifts an.

  • Für die erste Version des Konstruktors wird ein Wert von 0 ähnlich behandelt wie ein Wert von 1, mit der Ausnahme, dass die Breite nicht von Skalierungstransformationsvorgängen beeinflusst wird, die für das Grafikobjekt wirksam sind, für das der Stift verwendet wird; die Breite beträgt immer 1 Pixel.

  • Bei der zweiten Version des Konstruktors wird PS_GEOMETRICdie nPenStyle Breite in logischen Einheiten angegeben. Ist nPenStyle dies der Wert PS_COSMETIC, muss die Breite auf 1 festgelegt werden.

crColor
Enthält eine RGB-Farbe für den Stift.

pLogBrush
Verweist auf eine LOGBRUSH Struktur. Wenn nPenStyle dies der Wert istPS_COSMETIC, gibt das lbColor Element der LOGBRUSH Struktur die Farbe des Stifts und das lbStyle Element der LOGBRUSH Struktur auf .BS_SOLID Wenn nPenStyle ja PS_GEOMETRIC, müssen alle Member verwendet werden, um die Pinselattribute des Stifts anzugeben.

nStyleCount
Gibt die Länge des lpStyle Arrays in Doppelworteinheiten an. Dieser Wert muss null sein, wenn nPenStyle dies nicht PS_USERSTYLEder Fall ist.

lpStyle
Verweist auf ein Array von Doubleword-Werten. Der erste Wert gibt die Länge des ersten Gedankenstrichs in einer benutzerdefinierten Formatvorlage an, der zweite Wert gibt die Länge des ersten Leerzeichens usw. an. Dieser Zeiger muss sein NULL , wenn nPenStyle dies nicht PS_USERSTYLEder Fall ist.

Hinweise

Wenn Sie den Konstruktor ohne Argumente verwenden, müssen Sie das resultierende CPen Objekt mit den CreatePenFunktionen , CreatePenIndirectoder CreateStockObject Membern initialisieren.

Wenn Sie den Konstruktor verwenden, der Argumente verwendet, ist keine weitere Initialisierung erforderlich. Der Konstruktor mit Argumenten kann eine Ausnahme auslösen, wenn Fehler auftreten, während der Konstruktor ohne Argumente immer erfolgreich ist.

Beispiel

// Create a solid red pen of width 2.
CPen myPen1(PS_SOLID, 2, RGB(255, 0, 0));

// Create a geometric pen.
LOGBRUSH logBrush;
logBrush.lbStyle = BS_SOLID;
logBrush.lbColor = RGB(0, 255, 0);
CPen myPen2(PS_DOT | PS_GEOMETRIC | PS_ENDCAP_ROUND, 2, &logBrush);

CPen::CreatePen

Erstellt einen logischen kosmetischen oder geometrischen Stift mit den angegebenen Stil-, Breiten- und Pinselattributen und fügt ihn an das CPen Objekt an.

BOOL CreatePen(
    int nPenStyle,
    int nWidth,
    COLORREF crColor);

BOOL CreatePen(
    int nPenStyle,
    int nWidth,
    const LOGBRUSH* pLogBrush,
    int nStyleCount = 0,
    const DWORD* lpStyle = NULL);

Parameter

nPenStyle
Gibt die Formatvorlage für den Stift an. Eine Liste der möglichen Werte finden Sie im nPenStyle Parameter im CPen Konstruktor.

nWidth
Gibt die Breite des Stifts an.

  • Für die erste Version von CreatePen, wird ein Wert von 0 ähnlich behandelt wie ein Wert von 1, mit der Ausnahme, dass die Breite nicht von Skalierungstransformationsvorgängen beeinflusst wird, die für das Grafikobjekt wirksam sind, für das der Stift verwendet wird; die Breite beträgt immer 1 Pixel.

  • Bei der zweiten Version von CreatePen, wenn nPenStyle ja PS_GEOMETRIC, wird die Breite in logischen Einheiten angegeben. Ist nPenStyle dies der Wert PS_COSMETIC, muss die Breite auf 1 festgelegt werden.

crColor
Enthält eine RGB-Farbe für den Stift.

pLogBrush
Verweist auf eine LOGBRUSH Struktur. Wenn nPenStyle dies der Wert istPS_COSMETIC, gibt das lbColor Element der LOGBRUSH Struktur die Farbe des Stifts und das lbStyle Element der LOGBRUSH Struktur auf .BS_SOLID Wenn nPenStyle ja PS_GEOMETRIC, müssen alle Member verwendet werden, um die Pinselattribute des Stifts anzugeben.

nStyleCount
Gibt die Länge des lpStyle Arrays in Doppelworteinheiten an. Dieser Wert muss null sein, wenn nPenStyle dies nicht PS_USERSTYLEder Fall ist.

lpStyle
Verweist auf ein Array von Doubleword-Werten. Der erste Wert gibt die Länge des ersten Gedankenstrichs in einer benutzerdefinierten Formatvorlage an, der zweite Wert gibt die Länge des ersten Leerzeichens usw. an. Dieser Zeiger muss sein NULL , wenn nPenStyle dies nicht PS_USERSTYLEder Fall ist.

Rückgabewert

Nonzero bei erfolgreicher Ausführung oder Null, wenn die Methode fehlschlägt.

Hinweise

Die erste Version von CreatePen Initialisiert einen Stift mit der angegebenen Formatvorlage, Breite und Farbe. Der Stift kann anschließend als aktueller Stift für jeden Gerätekontext ausgewählt werden.

Stifte mit einer Breite von mehr als 1 Pixeln sollten immer entweder das Format PS_SOLIDoder PS_INSIDEFRAME die PS_NULLFormatvorlage aufweisen.

Wenn ein Stift die PS_INSIDEFRAME Formatvorlage und eine Farbe aufweist, die nicht mit einer Farbe in der logischen Farbtabelle übereinstimmt, wird der Stift mit einer gewürteten Farbe gezeichnet. Die PS_SOLID Stiftformatvorlage kann nicht verwendet werden, um einen Stift mit einer geerbten Farbe zu erstellen. Die Formatvorlage PS_INSIDEFRAME ist identisch mit PS_SOLID dem Wert, wenn die Stiftbreite kleiner oder gleich 1 ist.

Die zweite Version von CreatePen Initialisiert einen logischen kosmetischen oder geometrischen Stift mit den angegebenen Stil-, Breiten- und Pinselattributen. Die Breite eines kosmetischen Stifts ist immer 1; die Breite eines geometrischen Stifts wird immer in Welteinheiten angegeben. Nachdem eine Anwendung einen logischen Stift erstellt hat, kann er diesen Stift in einen Gerätekontext auswählen, indem die CDC::SelectObject Funktion aufgerufen wird. Nachdem ein Stift in einen Gerätekontext ausgewählt wurde, kann er verwendet werden, um Linien und Kurven zu zeichnen.

  • Wenn nPenStyle und PS_COSMETICPS_USERSTYLE, geben die Einträge im lpStyle Array Längen von Strichen und Leerzeichen in Formatvorlageneinheiten an. Eine Formatvorlage wird durch das Gerät definiert, auf dem der Stift zum Zeichnen einer Linie verwendet wird.

  • Wenn nPenStyle und PS_GEOMETRICPS_USERSTYLE, geben die Einträge im lpStyle Array Längen von Strichen und Leerzeichen in logischen Einheiten an.

  • Wenn nPenStyle ja PS_ALTERNATE, wird die Formatvorlageneinheit ignoriert, und jedes andere Pixel wird festgelegt.

Wenn eine Anwendung keinen bestimmten Stift mehr benötigt, sollte sie die CGdiObject::DeleteObject Memberfunktion aufrufen oder das CPen Objekt zerstören, sodass die Ressource nicht mehr verwendet wird. Eine Anwendung sollte keinen Stift löschen, wenn der Stift in einem Gerätekontext ausgewählt ist.

Beispiel

CPen myPen1, myPen2;

// Create a solid red pen of width 2.
myPen1.CreatePen(PS_SOLID, 2, RGB(255, 0, 0));

// Create a geometric pen.
LOGBRUSH logBrush;
logBrush.lbStyle = BS_SOLID;
logBrush.lbColor = RGB(0, 255, 0);
myPen2.CreatePen(PS_DOT | PS_GEOMETRIC | PS_ENDCAP_ROUND, 2, &logBrush);

CPen::CreatePenIndirect

Initialisiert einen Stift mit der Formatvorlage, Breite und Farbe in der Struktur, auf lpLogPendie verwiesen wird.

BOOL CreatePenIndirect(LPLOGPEN lpLogPen);

Parameter

lpLogPen
Verweist auf die Windows-Struktur LOGPEN , die Informationen zum Stift enthält.

Rückgabewert

Ist ungleich null (0), wenn die Funktion erfolgreich ausgeführt wird, andernfalls null (0).

Hinweise

Stifte mit einer Breite von mehr als 1 Pixeln sollten immer entweder das Format PS_SOLIDoder PS_INSIDEFRAME die PS_NULLFormatvorlage aufweisen.

Wenn ein Stift die PS_INSIDEFRAME Formatvorlage und eine Farbe aufweist, die nicht mit einer Farbe in der logischen Farbtabelle übereinstimmt, wird der Stift mit einer gewürteten Farbe gezeichnet. Die PS_INSIDEFRAME Formatvorlage ist identisch mit PS_SOLID dem Wert, wenn die Stiftbreite kleiner oder gleich 1 ist.

Beispiel

LOGPEN logpen;
CPen   cMyPen;

// Get the LOGPEN of an existing pen.
penExisting.GetLogPen(&logpen);

// Change the color to red and the width to 2.
logpen.lopnWidth.x = 2;
logpen.lopnColor = RGB(255, 0, 0);

// Create my pen using the new settings.
cMyPen.CreatePenIndirect(&logpen);

CPen::FromHandle

Gibt einen Zeiger auf ein CPen Objekt zurück, das einem Handle für ein Windows GDI-Stiftobjekt zugewiesen wurde.

static CPen* PASCAL FromHandle(HPEN hPen);

Parameter

hPen
HPEN handle to Windows GDI pen.

Rückgabewert

Ein Zeiger auf ein CPen Objekt bei erfolgreicher Ausführung; andernfalls NULL.

Hinweise

Wenn ein CPen Objekt nicht an das Handle angefügt ist, wird ein temporäres CPen Objekt erstellt und angefügt. Dieses temporäre CPen Objekt ist nur gültig, bis die Anwendung das nächste Mal leerlauf in der Ereignisschleife hat, zu dem zeitpunkt alle temporären Grafikobjekte gelöscht werden. Das temporäre Objekt ist also nur während der Verarbeitung einer Fenstermeldung gültig.

Beispiel

// Convert an HPEN to a CPen*.
// NOTE: hPen is a valid pen handle.
CPen* pPen = CPen::FromHandle(hPen);

CPen::GetExtLogPen

Ruft eine EXTLOGPEN zugrunde liegende Struktur ab.

int GetExtLogPen(EXTLOGPEN* pLogPen);

Parameter

pLogPen
Verweist auf eine EXTLOGPEN Struktur, die Informationen zum Stift enthält.

Rückgabewert

Ungleich Null, wenn erfolgreich, andernfalls 0 (Null).

Hinweise

Die EXTLOGPEN Struktur definiert die Stil-, Breiten- und Pinselattribute eines Stifts. Rufen Sie GetExtLogPen beispielsweise auf, um dem bestimmten Stil eines Stifts zu entsprechen.

Informationen zu Stiftattributen finden Sie in den folgenden Themen im Windows SDK:

Beispiel

Im folgenden Codebeispiel wird das Aufrufen GetExtLogPen der Attribute eines Stifts veranschaulicht und anschließend ein neuer, kosmetischer Stift mit derselben Farbe erstellt.

EXTLOGPEN extlogpen;
penExisting.GetExtLogPen(&extlogpen);
CPen penOther;
LOGBRUSH LogBrush = { extlogpen.elpBrushStyle, extlogpen.elpColor,
   extlogpen.elpHatch };
penOther.CreatePen(PS_COSMETIC, 1, &LogBrush);

CPen::GetLogPen

Ruft eine LOGPEN zugrunde liegende Struktur ab.

int GetLogPen(LOGPEN* pLogPen);

Parameter

pLogPen
Verweist auf eine LOGPEN Struktur, die Informationen zum Stift enthält.

Rückgabewert

Ungleich Null, wenn erfolgreich, andernfalls 0 (Null).

Hinweise

Die LOGPEN Struktur definiert den Stil, die Farbe und das Muster eines Stifts.

Rufen Sie GetLogPen beispielsweise auf, um dem bestimmten Stiftstil zu entsprechen.

Informationen zu Stiftattributen finden Sie in den folgenden Themen im Windows SDK:

Beispiel

Das folgende Codebeispiel veranschaulicht das Aufrufen GetLogPen eines Stiftzeichens und anschließendes Erstellen eines neuen einfarbigen Stifts mit derselben Farbe.

LOGPEN logpen;
penExisting.GetLogPen(&logpen);
CPen penOther(PS_SOLID, 0, logpen.lopnColor);

CPen::operator HPEN

Ruft das angefügte Windows GDI-Handle des CPen Objekts ab.

operator HPEN() const;

Rückgabewert

Bei erfolgreicher Ausführung ein Handle für das Windows GDI-Objekt, das durch das CPen Objekt dargestellt wird; andernfalls NULL.

Hinweise

Dieser Operator ist ein Umwandlungsoperator, der die direkte Verwendung eines HPEN Objekts unterstützt.

Weitere Informationen zur Verwendung von Grafikobjekten finden Sie im Artikel "Grafikobjekte " im Windows SDK.

Beispiel

// Create a solid red pen of width 2.
CPen myPen(PS_SOLID, 2, RGB(255, 0, 0));

// Get the handle of the pen object.
HPEN hPen = (HPEN)myPen;

Siehe auch

CGdiObject Klasse
Hierarchiediagramm
CBrush Klasse