CPen 類別
封裝 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 的詳細資訊，請參閱 繪圖物件 。
繼承階層架構
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 ，這個值必須是零。
lpStyle
指向雙字值的陣列。 第一個值會指定使用者定義樣式中第一個虛線的長度、第二個值指定第一個空格的長度等等。 如果 nPenStyle 不是 PS_USERSTYLE ，這個指標必須是 NULL 。
傳回值
如果成功，則為非零，如果方法失敗則為零。
備註
的第一個版本 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;
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應