# Function Reference

# _WinAPI_CreatePen

Creates a logical pen that has the specified style, width, and color

#include <WinAPIGdi.au3>
_WinAPI_CreatePen ( $iPenStyle, $iWidth, $iColor )

## Parameters

$iPenStyle | Specifies the pen style. It can be any one of the following values. PS_SOLID - The pen is solid. PS_DASH - The pen is dashed. This style is valid only when the pen width is one or less in device units. PS_DOT - The pen is dotted. This style is valid only when the pen width is one or less in device units. PS_DASHDOT - The pen has alternating dashes and dots. This style is valid only when the pen width is one or less in device units. PS_DASHDOTDOT - The pen has alternating dashes and double dots. This style is valid only when the pen width is one or less in device units. PS_NULL - The pen is invisible. PS_INSIDEFRAME - The pen is solid. When this pen is used in any GDI drawing function that takes a bounding rectangle, the dimensions of the figure are shrunk so that it fits entirely in the bounding rectangle, taking into account the width of the pen. This applies only to geometric pens.
$iWidth | Specifies the width of the pen, in logical units.
$iColor | Specifies the color of the pen (BGR)

## Return Value

Success: | HPEN Value that identifies a logical pen
Failure: | 0

## Remarks

The pen can subsequently be selected into a device context and used to draw lines and curves.
After an application creates a logical pen, it can select that pen into a device context by calling the _WinAPI_SelectObject() function. After a pen is selected into a device context, it can be used to draw lines and curves.
If the value specified by the $iWidth parameter is zero, a line drawn with the created pen always is a single pixel wide regardless of the current transformation.
If the value specified by $iWidth is greater than 1, the $iPenStyle parameter must be PS_NULL, PS_SOLID, or PS_INSIDEFRAME.
When you no longer need the pen, call the DeleteObject function to delete it.

## Related

_WinAPI_DeleteObject, _WinAPI_DrawLine, _WinAPI_GetBkMode, _WinAPI_LineTo, _WinAPI_MoveTo, _WinAPI_SelectObject, _WinAPI_SetBkMode

## See Also

Search CreatePen in MSDN Library.

## Example

    #include <MsgBoxConstants.au3>
    #include <WinAPIGdi.au3>
    #include <WinAPIGdiDC.au3>
    #include <WinAPIHObj.au3>
    #include <WinAPISysWin.au3>

    If Not @Compiled Then Exit MsgBox($MB_ICONWARNING, "_WinAPI_CreatePen Example Script", _
            "When run from SciTE the script won't work properly because SciTE refreshes the screen. Hence the cross does not get fully drawn and disappears in a split second!" & _
            @CRLF & @CRLF & "Please compile the script and run the Exe.")

    ShowCross(@DesktopWidth / 2, @DesktopHeight / 2, 20, 2, 0xFF, 3000)

    Func ShowCross($iStart_x, $iStart_y, $iLength, $iWidth, $iColor, $iTime)
        Local $hDC, $hPen, $o_Orig

        $hDC = _WinAPI_GetWindowDC(0) ; DC of entire screen (desktop)
        $hPen = _WinAPI_CreatePen($PS_SOLID, $iWidth, $iColor)
        $o_Orig = _WinAPI_SelectObject($hDC, $hPen)

        _WinAPI_DrawLine($hDC, $iStart_x - $iLength, $iStart_y, $iStart_x - 5, $iStart_y) ; horizontal left
        _WinAPI_DrawLine($hDC, $iStart_x + $iLength, $iStart_y, $iStart_x + 5, $iStart_y) ; horizontal right
        _WinAPI_DrawLine($hDC, $iStart_x, $iStart_y - $iLength, $iStart_x, $iStart_y - 5) ; vertical up
        ;   _WinAPI_DrawLine($hDC, $iStart_x, $iStart_y + $iLength, $iStart_x, $iStart_y + 5) ; vertical down
        _WinAPI_MoveTo($hDC, $iStart_x, $iStart_y + $iLength)
        _WinAPI_LineTo($hDC, $iStart_x, $iStart_y + 5)

        Sleep($iTime) ; show cross over screen for defined seconds

        ; refresh desktop (clear cross)
        _WinAPI_RedrawWindow(_WinAPI_GetDesktopWindow(), 0, 0, $RDW_INVALIDATE + $RDW_ALLCHILDREN)

        ; clear resources
        _WinAPI_SelectObject($hDC, $o_Orig)
        _WinAPI_DeleteObject($hPen)
        _WinAPI_ReleaseDC(0, $hDC)
    EndFunc   ;==>ShowCross