DrawSetStroke - ProGUI Reference Manual

Syntax

DrawSetStroke(Width.f, Flags=#Null, DashStartOffset.f=0)

Description

Sets the properties for subsequent stroke operations (drawing lines or outlines of shapes like boxes, ellipses, paths). This includes the width, style (solid, dashed, dotted), end cap style, and corner join style.

Parameters

Width.f
The desired width of the stroke in device-independent pixels (DIPs). A width of 0 or less may result in no stroke being drawn.

Flags (optional)
A combination of flags to control the stroke's appearance. Default is #Null (solid line, default caps/joins).

; Dash Style (mutually exclusive unless using Custom)
#PG_Stroke_Dash        : Use a standard dashed line pattern (e.g., -- --).
#PG_Stroke_Dot         : Use a standard dotted line pattern (e.g., . . . ). Automatically forces round caps/corners.
#PG_Stroke_CustomDash  : Use a custom dash pattern set by DrawSetStrokeCustom().

; DPI Scaling
#PG_Stroke_NoDPIScaling: The stroke Width is interpreted as physical pixels and not scaled by DPI.

; End Cap Style (how line ends are drawn)
#PG_Stroke_RoundEnd    : Use rounded end caps.
#PG_Stroke_SquareEnd   : Use square end caps that extend beyond the line endpoint.
; Default (no flag)    : Use flat end caps (#D2D1_CAP_STYLE_FLAT / #CAIRO_LINE_CAP_BUTT).

; Corner Join Style (how corners in paths/boxes are drawn)
#PG_Stroke_RoundCorner : Use rounded joins.
#PG_Stroke_BevelCorner : Use beveled (flattened) joins.
; Default (no flag)    : Use mitered joins (#D2D1_LINE_JOIN_MITER / #CAIRO_LINE_JOIN_MITER), potentially limited by MiterLimit.

; Stroke Alignment (relative to the geometric line/outline)
#PG_Stroke_Center      : Center the stroke thickness on the geometric line (half inside, half outside).
#PG_Stroke_Outside     : Draw the stroke entirely outside the geometric shape/line.
; Default (no flag)    : Draw the stroke mostly inside the geometric shape/line (default Direct2D/Cairo behavior, may vary slightly).

DashStartOffset.f (optional)
Specifies an offset into the dash pattern sequence, measured in units of stroke width. Used to animate dashed lines ("marching ants"). Default is 0.

Return Value

This command does not return a value.

Remarks

The settings persist until changed again or until the drawing state is restored via DrawRestore(). The stroke width is specified in DIPs (unless #PG_Stroke_NoDPIScaling is used) and scaled internally. For custom dash patterns, DrawSetStrokeCustom() must be called separately *before* setting the #PG_Stroke_CustomDash flag here. The default stroke is a 1 DIP solid line with flat caps and mitered joins.

Example

IncludeFile "ProGUI_PB.pbi"

StartProGUI()

Procedure DrawHandler(Window, EventType, *EventData.PG_EventDraw, *UserData)
  Static offset.f
  
    DrawClear(RGB(255, 255, 255), 1)

    ; Line 1: Default 1px solid
    DrawLine(10, 20, 150, 20, RGB(0,0,0))

    ; Line 2: 5px, red, dashed, round ends/corners
    DrawSetStroke(5, #PG_Stroke_Dash | #PG_Stroke_RoundEnd | #PG_Stroke_RoundCorner)
    DrawLine(10, 50, 150, 50, RGB(255, 0, 0))
    DrawBoxStroke(170, 20, 50, 50, RGB(255,0,0)) ; Box uses same stroke

    ; Line 3: 3px, blue, dotted (forces round ends/corners implicitly)
    DrawSetStroke(3, #PG_Stroke_Dot)
    DrawLine(10, 80, 150, 80, RGB(0, 0, 255))

    ; Line 4: Animated dash offset
    DrawSetStroke(2, #PG_Stroke_Dash, offset)
    DrawLine(10, 110, 150, 110, RGB(0, 128, 0))
    offset + 0.1 ; Increment offset for next frame

    ; Restore default stroke
    DrawSetStroke(1)

EndProcedure

MyWindow = CreateWindow(0, 0, 240, 150, "DrawSetStroke Example")

If MyWindow
  AddEventHandler(MyWindow, #PG_Event_Draw, @DrawHandler())
  WindowShow(MyWindow, #True, #PG_Window_ScreenCentered)

  Repeat
    Event = WaitWindowEvent()
  Until Event = #PB_Event_CloseWindow
EndIf

StopProGUI()

Supported OS

Windows, Linux