`CPen` 類別

發行項
07/05/2024

封裝 Windows 繪圖裝置介面 (GDI) 畫筆。

語法

class CPen : public CGdiObject

成員

公用建構函式

名稱	描述
`CPen::CPen`	建構 `CPen` 物件。

公用方法

名稱	描述
`CPen::CreatePen`	建立具有指定樣式、寬度和筆刷屬性的邏輯外觀或幾何畫筆，並將它附加至 `CPen` 物件。
`CPen::CreatePenIndirect`	建立具有結構中 `LOGPEN` 指定之樣式、寬度和色彩的畫筆，並將它附加至 `CPen` 物件。
`CPen::FromHandle`	當指定 Windows HPEN 時，傳回物件的指標 `CPen` 。
`CPen::GetExtLogPen`	`EXTLOGPEN`取得基礎結構。
`CPen::GetLogPen`	`LOGPEN`取得基礎結構。

公用運算子

名稱	描述
`CPen::operator HPEN`	傳回附加至 `CPen` 物件的 Windows 句柄。

備註

如需使用 CPen的詳細資訊，請參閱圖形物件。

繼承階層架構

CObject

CGdiObject

CPen

需求

標頭： afxwin.h

`CPen::CPen`

建構 CPen 物件。

CPen();

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

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

參數

nPenStyle
指定畫筆樣式。建構函式第一個版本中的這個參數可以是下列其中一個值：

PS_SOLID 建立實心畫筆。
PS_DASH 建立虛線畫筆。只有在畫筆寬度為 1 或更少時，才會在裝置單位中有效。
PS_DOT 建立虛線畫筆。只有在畫筆寬度為 1 或更少時，才會在裝置單位中有效。
PS_DASHDOT 建立具有交替虛線和點的畫筆。只有在畫筆寬度為 1 或更少時，才會在裝置單位中有效。
PS_DASHDOTDOT 建立具有交替虛線和雙點的畫筆。只有在畫筆寬度為 1 或更少時，才會在裝置單位中有效。
PS_NULL 建立 Null 手寫筆。
PS_INSIDEFRAME 建立畫筆，在 Windows GDI 輸出函式所產生的封閉圖案框架內繪製線條，以指定周框（例如 Ellipse、 Rectangle、、 RoundRect、 Pie和 Chord 成員函式）。當此樣式與未指定周框的 Windows GDI 輸出函式搭配使用時（例如 LineTo 成員函式），畫筆的繪圖區域不受框架限制。

建構函式的第二個版本 CPen 會指定類型、樣式、結束帽和聯結屬性的組合。每個類別的值都應該使用位「or」（|）運算子來結合。畫筆類型可以是下列其中一個值：

PS_GEOMETRIC 建立幾何畫筆。
PS_COSMETIC 建立整容筆。

建構函式的第二個版本 CPen 會為 nPenStyle新增下列畫筆樣式：
PS_ALTERNATE 建立一個畫筆，以設定所有其他圖元。（此樣式僅適用於整容筆。
PS_USERSTYLE 建立使用使用者所提供的樣式陣列的畫筆。

結束上限可以是下列其中一個值：
PS_ENDCAP_ROUND 結束上限是圓角。
PS_ENDCAP_SQUARE 端點為正方形。
PS_ENDCAP_FLAT 端點上限是平面的。

聯結可以是下列其中一個值：
PS_JOIN_BEVEL 聯結會斜面。
PS_JOIN_MITER 聯結在函式所設定的目前限制內時，會遭到誤判 SetMiterLimit 。如果聯結超過此限制，則會斜面。
PS_JOIN_ROUND 聯結為圓形。

nWidth
指定畫筆的寬度。

對於建構函式的第一個版本，0 的值會與 1 的值類似，不同之處在於寬度不會受到手寫筆所使用之 Graphics 物件的縮放轉換作業所影響：寬度一律為 1 圖元。
對於建構函式的第二個版本，如果 nPenStyle 為 PS_GEOMETRIC，則會以邏輯單位指定寬度。如果 nPenStyle 為 PS_COSMETIC，則寬度必須設定為1。

crColor
包含畫筆的 RGB 色彩。

pLogBrush
LOGBRUSH指向結構。如果 nPenStyle 為 PS_COSMETIC，結構 lbColor 的成員 LOGBRUSH 會指定畫筆的色彩，而且 lbStyle 結構的成員 LOGBRUSH 必須設定為 BS_SOLID。如果 nPenStyle 為 PS_GEOMETRIC，則必須使用所有成員來指定畫筆的筆刷屬性。

nStyleCount
指定數位的雙字單位 lpStyle 長度。如果 nPenStyle 不是 PS_USERSTYLE，這個值必須是零。

lpStyle
指向雙字值的陣列。第一個值會指定使用者定義樣式中第一個虛線的長度、第二個值指定第一個空格的長度等等。如果 nPenStyle 不是 PS_USERSTYLE，這個指標必須是 NULL 。

備註

如果您使用不含自變數的建構函式，則必須使用CreatePen、 CreatePenIndirect或 CreateStockObject 成員函式初始化產生的CPen物件。

如果您使用採用自變數的建構函式，則不需要進一步初始化。如果遇到錯誤，具有自變數的建構函式可能會擲回例外狀況，而沒有自變數的建構函式一律會成功。

範例

// 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`

建立具有指定樣式、寬度和筆刷屬性的邏輯外觀或幾何畫筆，並將它附加至 CPen 物件。

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

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

參數

nPenStyle
指定畫筆的樣式。如需可能值的清單，請參閱 nPenStyle 建構函式中的 CPen 參數。

nWidth
指定畫筆的寬度。

在第一個版本的 CreatePen中，值0會與1的值類似，不同之處在於寬度不會受到手寫筆所使用之 Graphics 物件的縮放轉換作業所影響;寬度一律為1圖元。
如果是，則為的第二個版本CreatePennPenStylePS_GEOMETRIC，則寬度會以邏輯單位表示。如果 nPenStyle 為 PS_COSMETIC，則寬度必須設定為1。

crColor
包含畫筆的 RGB 色彩。

pLogBrush
LOGBRUSH指向結構。如果 nPenStyle 為 PS_COSMETIC，結構 lbColor 的成員 LOGBRUSH 會指定畫筆的色彩，而且 lbStyle 結構的成員 LOGBRUSH 必須設定為 BS_SOLID。如果 nPenStyle 為 PS_GEOMETRIC，則必須使用所有成員來指定畫筆的筆刷屬性。

nStyleCount
指定數位的雙字單位 lpStyle 長度。如果 nPenStyle 不是 PS_USERSTYLE，這個值必須是零。

傳回值

如果成功，則為非零，如果方法失敗則為零。

備註

的第一個版本 CreatePen 會使用指定的樣式、寬度和色彩，初始化手寫筆。接著可以將畫筆選取為任何裝置內容的目前畫筆。

寬度大於 1 像素的 PS_NULL畫筆應該一律具有、 PS_SOLID或 PS_INSIDEFRAME 樣式。

如果畫筆的 PS_INSIDEFRAME 樣式和色彩不符合邏輯色彩表格中的色彩，則畫筆會以彩色繪製。畫 PS_SOLID 筆樣式無法用來建立具有任一色彩的畫筆。 PS_INSIDEFRAME如果畫筆寬度小於或等於 1，樣式會與 PS_SOLID 相同。

的第二個版本 CreatePen 會初始化具有指定樣式、寬度和筆刷屬性的邏輯外觀或幾何畫筆。整容筆的寬度一律為 1;幾何畫筆的寬度一律以世界單位指定。應用程式建立邏輯畫筆之後，可以藉由呼叫 CDC::SelectObject 函式來選取該畫筆到裝置內容中。將畫筆選取到裝置內容之後，即可用來繪製線條和曲線。

如果 nPenStyle 為 PS_COSMETIC 和 PS_USERSTYLE，則陣列中的 lpStyle 專案會以樣式單位指定虛線和空格的長度。樣式單位是由畫筆用來繪製線條的裝置所定義。
如果 nPenStyle 為 PS_GEOMETRIC 和 PS_USERSTYLE，則陣列中的 lpStyle 專案會以邏輯單位指定破折號和空格的長度。
如果 nPenStyle 為 PS_ALTERNATE，則會忽略樣式單位，並設定其他每個圖元。

當應用程式不再需要指定的畫筆時，它應該呼叫 CGdiObject::DeleteObject 成員函式或終結 CPen 物件，讓資源不再使用。在裝置內容中選取畫筆時，應用程式不應該刪除畫筆。

範例

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`

初始化手寫筆，此畫筆具有所指向 lpLogPen之結構中指定的樣式、寬度和色彩。

BOOL CreatePenIndirect(LPLOGPEN lpLogPen);

參數

lpLogPen
指向包含畫筆相關信息的 Windows LOGPEN 結構。

傳回值

如果函式成功則為非零，否則為 0。

備註

寬度大於 1 像素的 PS_NULL畫筆應該一律具有、 PS_SOLID或 PS_INSIDEFRAME 樣式。

如果畫筆的 PS_INSIDEFRAME 樣式和色彩不符合邏輯色彩表格中的色彩，則畫筆會以彩色繪製。如果畫筆寬度小於或等於 1，樣式 PS_INSIDEFRAME 會與 PS_SOLID 相同。

範例

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`

傳回物件指標 CPen ，指定 Windows GDI 手寫筆物件的句柄。

static CPen* PASCAL FromHandle(HPEN hPen);

參數

hPen
HPEN Windows GDI 手寫筆的句柄。

傳回值

如果成功， CPen 則為物件的指標，否則 NULL為。

備註

CPen如果物件未附加至句柄，則會建立並附加暫存CPen物件。這個暫存 CPen 物件只有在下次應用程式在其事件迴圈中有閑置時間為止才有效，此時會刪除所有暫存圖形物件。換句話說，暫存物件只有在處理一個視窗訊息期間才有效。

範例

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

`CPen::GetExtLogPen`

EXTLOGPEN取得基礎結構。

int GetExtLogPen(EXTLOGPEN* pLogPen);

參數

pLogPen
指向 EXTLOGPEN 包含畫筆相關信息的結構。

傳回值

如果成功則為非零；否則為 0。

備註

結構 EXTLOGPEN 會定義畫筆的樣式、寬度和筆刷屬性。例如，呼叫 GetExtLogPen 以符合畫筆的特定樣式。

如需手寫筆屬性的相關信息，請參閱 Windows SDK 中的下列主題：

範例

下列程式代碼範例示範呼叫 GetExtLogPen 以擷取畫筆的屬性，然後建立具有相同色彩的新外觀畫筆。

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

`CPen::GetLogPen`

LOGPEN取得基礎結構。

int GetLogPen(LOGPEN* pLogPen);

參數

pLogPen
LOGPEN指向結構以包含手寫筆的相關信息。

傳回值

如果成功則為非零；否則為 0。

備註

結構 LOGPEN 會定義畫筆的樣式、色彩和圖樣。

例如，呼叫 GetLogPen 以符合特定手寫筆樣式。

如需手寫筆屬性的相關信息，請參閱 Windows SDK 中的下列主題：

範例

下列程式代碼範例示範呼叫 GetLogPen 以擷取畫筆字元，然後建立具有相同色彩的新純色畫筆。

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

`CPen::operator HPEN`

取得物件的附加 Windows GDI 句柄 CPen 。

operator HPEN() const;

傳回值

如果成功，則為物件所 CPen 代表之 Windows GDI 物件的句柄，否則 NULL為。

備註

這個運算子是一個轉型運算元，可支援直接使用 HPEN 物件。

如需使用圖形對象的詳細資訊，請參閱 Windows SDK 中的圖形物件一文。

範例

// 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;

另請參閱

CGdiObject 類
 階層架構圖表
 CBrush 類

共用方式為

CPen 類別

語法

成員

公用建構函式

公用方法

公用運算子

備註

繼承階層架構

需求

CPen::CPen

參數

備註

範例

CPen::CreatePen

參數

傳回值

備註

範例

CPen::CreatePenIndirect

參數

傳回值

備註

範例

CPen::FromHandle

參數

傳回值

備註

範例

CPen::GetExtLogPen

參數

傳回值

備註

範例

CPen::GetLogPen

參數

傳回值

備註

範例

CPen::operator HPEN

傳回值

備註

範例