ExtCreatePen 函式 (wingdi.h)

發行項
08/27/2023

ExtCreatePen函式會建立具有指定樣式、寬度和筆刷屬性的邏輯外觀或幾何畫筆。

語法

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

參數

[in] iPenStyle

類型、樣式、結束端點和聯結屬性的組合。每個類別的值都會使用位 OR 運算子來結合 ( |) 。

畫筆類型可以是下列其中一個值。

值	意義
PS_GEOMETRIC	畫筆是幾何的。
PS_COSMETIC	手寫筆外觀。

畫筆樣式可以是下列其中一個值。

值	意義
PS_ALTERNATE	畫筆會設定所有其他圖元。 (此樣式僅適用于外觀畫筆。)
PS_SOLID	畫筆為實心。
PS_DASH	畫筆虛線。
PS_DOT	畫筆會虛線。
PS_DASHDOT	手寫筆有交替的虛線和點。
PS_DASHDOTDOT	手寫筆有交替的虛線和雙點。
PS_Null	手寫筆是看不見的。
PS_USERSTYLE	畫筆會使用使用者所提供的樣式陣列。
PS_INSIDEFRAME	畫筆為實心。當此畫筆用於採用周框的任何 GDI 繪圖函式時，圖形的維度會壓縮，使其完全放入周框，並考慮手寫筆的寬度。這只適用于幾何手寫筆。

只針對幾何手寫筆指定結束端點。結尾上限可以是下列其中一個值。

值	意義
PS_ENDCAP_ROUND	結束端點會四捨五入。
PS_ENDCAP_SQUARE	結束端點為正方形。
PS_ENDCAP_FLAT	結束端點是平面的。

只有幾何畫筆指定聯結。聯結可以是下列其中一個值。

值	意義
PS_JOIN_BEVEL	聯結會斜面。
PS_JOIN_MITER	當聯結在 SetMiterLimit 函式所設定的目前限制內時，聯結會遭到調整。如果超過此限制，聯結會斜面。
PS_JOIN_ROUND	聯結會四捨五入。

[in] cWidth

畫筆的寬度。如果 dwPenStyle 參數是PS_GEOMETRIC，則會以邏輯單位提供寬度。如果 dwPenStyle 是PS_COSMETIC，寬度必須設定為 1。

[in] plbrush

LOGBRUSH結構的指標。如果 dwPenStyle 是PS_COSMETIC， lbColor 成員會指定畫筆的色彩，而 lpStyle 成員必須設定為 BS_SOLID。如果 dwPenStyle 是PS_GEOMETRIC，則必須使用所有成員來指定畫筆的筆刷屬性。

[in] cStyle

lpStyle陣列的長度，以DWORD單位為單位。如果 dwPenStyle 不是PS_USERSTYLE，這個值就必須是零。

樣式計數限制為 16。

[in] pstyle

陣列的指標。第一個值會指定使用者定義樣式中第一個虛線的長度，第二個值會指定第一個空格的長度，依此類故。如果dwPenStyle未PS_USERSTYLE，此指標必須是Null。

如果線上條繪製期間超過 lpStyle 陣列，指標會重設為數組的開頭。當發生這種情況且 dwStyleCount 是偶數時，虛線和空格的圖樣會重複。不過，如果 dwStyleCount 是奇數的，當指標重設時，模式會反轉 -- lpStyle 的第一個專案現在是指空格，第二個元素會參考虛線等等。

傳回值

如果函式成功，則傳回值是識別邏輯手寫筆的控制碼。

如果此函式失敗，則傳回值為零。

備註

幾何畫筆可以有任何寬度，而且可以有筆刷的任何屬性，例如 dithers 和 patterns。外觀畫筆只能是單一圖元寬，而且必須是純色，但外觀畫筆通常比幾何畫筆更快。

幾何畫筆的寬度一律以世界單位指定。外觀畫筆的寬度一律為 1。

只針對幾何畫筆指定端點和聯結。

應用程式建立邏輯畫筆之後，可以藉由呼叫 SelectObject 函式，將該畫筆選取到裝置內容中。將手寫筆選取到裝置內容之後，即可用來繪製線條和曲線。

如果 dwPenStyle 是PS_COSMETIC且PS_USERSTYLE， lpStyle 陣列中的專案會以樣式單位指定虛線和空格的長度。樣式單位是由用來繪製線條的裝置所定義。

如果 dwPenStyle 是PS_GEOMETRIC且PS_USERSTYLE， 則 lpStyle 陣列中的專案會以邏輯單位指定虛線和空格的長度。

如果 dwPenStyle 是PS_ALTERNATE，則會忽略樣式單位，並設定所有其他圖元。

如果lplb所指向之 LOGBRUSH結構的lbStyle成員BS_PATTERN，該結構的lbHatch成員所指向的點陣圖不能是 DIB 區段。 DIB 區段是由 CreateDIBSection所建立的點陣圖。如果該點陣圖是 DIB 區段， ExtCreatePen 函式會失敗。

當應用程式不再需要指定的手寫筆時，它應該呼叫 DeleteObject 函式來刪除手寫筆。

Icm： 手寫筆建立時不會進行色彩管理。不過，當畫筆選取為啟用 ICM 的裝置內容時，就會執行色彩管理。

範例

如需範例，請參閱使用手寫筆。

規格需求


最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	wingdi.h (包含 Windows.h)
程式庫	Gdi32.lib
Dll	Gdi32.dll