# Function Reference

# _WinAPI_ExtCreatePen

Creates a logical cosmetic or geometric pen that has the specified style, width, and brush attributes

#include <WinAPIGdi.au3>
_WinAPI_ExtCreatePen ( $iPenStyle, $iWidth, $iBrushStyle, $iRGB [, $iHatch = 0 [, $aUserStyle = 0 [, $iStart = 0 [, $iEnd = -1]]]] )

## Parameters

$iPenStyle | A combination of type, style, end cap, and join attributes. The values from each category are combined by using the bitwise operation. The pen type can be one of the following values. $PS_GEOMETRIC $PS_COSMETIC The pen style can be one of the following values. $PS_SOLID $PS_DASH $PS_DOT $PS_DASHDOT $PS_DASHDOTDOT $PS_NULL $PS_INSIDEFRAME $PS_USERSTYLE $PS_ALTERNATE The end cap is only specified for geometric pens and can be one of the following values. $PS_ENDCAP_ROUND $PS_ENDCAP_SQUARE $PS_ENDCAP_FLAT The join is only specified for geometric pens and can be one of the following values. $PS_JOIN_BEVEL $PS_JOIN_MITER $PS_JOIN_ROUND
$iWidth | The width of the pen. If $PS_GEOMETRIC type is specified, the width is given in logical units, otherwise, the width must be set to 1.
$iBrushStyle | A brush style. This parameter can be one of the $BS_* constants.
$iRGB | The color of a pen, in RGB.
$iHatch | [optional] A hatch style. For more information, see _WinAPI_CreateBrushIndirect().
$aUserStyle | [optional] The array (dash1, space1, dash2, space2, ... dashN, spaceN) that contains the length of the dashes and spaces in a user-defined style. The first value specifies the length of the first dash, the second value specifies the length of the first space, and so on. This parameter is ignored if $PS_USERSTYLE style is not specified. The style count is limited to 16.
$iStart | [optional] The index of array to start filling at.
$iEnd | [optional] The index of array to stop filling at.

## Return Value

Success: | Handle to the logical pen.
Failure: | 0.

## Remarks

After an application creates a pen by calling _WinAPI_ExtCreatePen(), it can select it into any device context by calling the _WinAPI_SelectObject() function.
When an application no longer requires a specified pen, it should call the _WinAPI_DeleteObject() function to delete the pen.

## Related

_WinAPI_DeleteObject, _WinAPI_SelectObject

## See Also

Search ExtCreatePen in MSDN Library.

## Example

    #include "Extras\HelpFileInternals.au3"

    #include <GUIConstantsEx.au3>
    #include <SendMessage.au3>
    #include <StaticConstants.au3>
    #include <WinAPIGdi.au3>
    #include <WinAPIGdiDC.au3>
    #include <WinAPIHObj.au3>
    #include <WinAPIRes.au3>
    #include <WinAPISysWin.au3>
    #include <WindowsSysColorConstants.au3>

    ; Create GUI
    Local $hForm = GUICreate('Test ' & StringReplace(@ScriptName, '.au3', '()'), 310, 300)
    Local $idPic = GUICtrlCreatePic('', 0, 0, 310, 300)
    Local $hPic = GUICtrlGetHandle($idPic)

    ; Create bitmap
    Local $hDC = _WinAPI_GetDC($hPic)
    Local $hMemDC = _WinAPI_CreateCompatibleDC($hDC)
    Local $hBitmap = _WinAPI_CreateCompatibleBitmapEx($hDC, 310, 300, _WinAPI_SwitchColor(_WinAPI_GetSysColor($COLOR_3DFACE)))
    Local $hMemSv = _WinAPI_SelectObject($hMemDC, $hBitmap)

    ; Draw a lines with a variety of type, style, end cap, and join attributes
    Local $hPen = _WinAPI_ExtCreatePen(BitOR($PS_GEOMETRIC, $PS_SOLID, $PS_ENDCAP_ROUND), 5, $BS_SOLID, 0)
    Local $hSv = _WinAPI_SelectObject($hMemDC, $hPen)
    _WinAPI_DrawLine($hMemDC, 20, 30, 289, 30)
    _WinAPI_SelectObject($hMemDC, $hSv)
    _WinAPI_DeleteObject($hPen)

    $hPen = _WinAPI_ExtCreatePen(BitOR($PS_GEOMETRIC, $PS_DASH, $PS_ENDCAP_ROUND), 5, $BS_SOLID, 0)
    $hSv = _WinAPI_SelectObject($hMemDC, $hPen)
    _WinAPI_DrawLine($hMemDC, 20, 70, 289, 70)
    _WinAPI_SelectObject($hMemDC, $hSv)
    _WinAPI_DeleteObject($hPen)

    $hPen = _WinAPI_ExtCreatePen(BitOR($PS_GEOMETRIC, $PS_DOT, $PS_ENDCAP_ROUND), 5, $BS_SOLID, 0)
    $hSv = _WinAPI_SelectObject($hMemDC, $hPen)
    _WinAPI_DrawLine($hMemDC, 20, 110, 289, 110)
    _WinAPI_SelectObject($hMemDC, $hSv)
    _WinAPI_DeleteObject($hPen)

    $hPen = _WinAPI_ExtCreatePen(BitOR($PS_GEOMETRIC, $PS_DASHDOT, $PS_ENDCAP_SQUARE), 5, $BS_SOLID, 0)
    $hSv = _WinAPI_SelectObject($hMemDC, $hPen)
    _WinAPI_DrawLine($hMemDC, 20, 150, 289, 150)
    _WinAPI_SelectObject($hMemDC, $hSv)
    _WinAPI_DeleteObject($hPen)

    $hPen = _WinAPI_ExtCreatePen(BitOR($PS_GEOMETRIC, $PS_DASHDOTDOT, $PS_ENDCAP_SQUARE), 5, $BS_SOLID, 0)
    $hSv = _WinAPI_SelectObject($hMemDC, $hPen)
    _WinAPI_DrawLine($hMemDC, 20, 190, 289, 190)
    _WinAPI_SelectObject($hMemDC, $hSv)
    _WinAPI_DeleteObject($hPen)

    Local $aStyle[6] = [1, 7, 1, 7, 1, 25]
    $hPen = _WinAPI_ExtCreatePen(BitOR($PS_GEOMETRIC, $PS_USERSTYLE, $PS_ENDCAP_ROUND), 5, $BS_SOLID, 0, 0, $aStyle)
    $hSv = _WinAPI_SelectObject($hMemDC, $hPen)
    _WinAPI_DrawLine($hMemDC, 20, 230, 289, 230)
    _WinAPI_SelectObject($hMemDC, $hSv)
    _WinAPI_DeleteObject($hPen)

    Local $sBmp = _Extras_PathFull('Pen.bmp')
    Local $hPattern = _WinAPI_LoadImage(0, $sBmp, $IMAGE_BITMAP, 0, 0, $LR_LOADFROMFILE)
    $hPen = _WinAPI_ExtCreatePen(BitOR($PS_GEOMETRIC, $PS_SOLID, $PS_ENDCAP_ROUND), 5, $BS_PATTERN, 0, $hPattern, $aStyle)
    $hSv = _WinAPI_SelectObject($hMemDC, $hPen)
    _WinAPI_DrawLine($hMemDC, 20, 270, 289, 270)
    _WinAPI_SelectObject($hMemDC, $hSv)
    _WinAPI_DeleteObject($hPattern)
    _WinAPI_DeleteObject($hPen)

    ; Release objects
    _WinAPI_ReleaseDC($hPic, $hDC)
    _WinAPI_SelectObject($hMemDC, $hMemSv)
    _WinAPI_DeleteDC($hMemDC)

    ; Set bitmap to control
    _SendMessage($hPic, $STM_SETIMAGE, 0, $hBitmap)
    Local $hObj = _SendMessage($hPic, $STM_GETIMAGE)
    If $hObj <> $hBitmap Then
        _WinAPI_DeleteObject($hBitmap)
    EndIf

    GUISetState(@SW_SHOW)

    Do
    Until GUIGetMsg() = $GUI_EVENT_CLOSE