BeginClipPath - ProGUI Reference Manual

Syntax

BeginClipPath(Flags=#Null)

Description

Sets the clipping region for subsequent drawing operations to the geometry defined by the current path. Any drawing that occurs outside the path's shape will be clipped (not rendered). The current path must be defined using path commands (PathMoveTo(), PathAddLine(), etc.) before calling this function. Each call to BeginClipPath() must be paired with a corresponding call to EndClip().

Parameters

Flags (optional)
Optional flags to modify the behavior. Currently, only relevant for the Direct2D backend.

#PG_Antialias_Aliased: Specifies that the edges of the clipping path should be aliased (not anti-aliased).
                       Default is #PG_Antialias_PerPrimitive which uses anti-aliasing.

Return Value

This command does not return a value.

Remarks

The path geometry is defined in device-independent pixels (DIPs) but converted internally based on the current output's DPI. Clipping regions are cumulative; nested calls will result in an intersection of the clipping areas. The path itself is consumed by this command unless the #PG_Path_Preserve flag was used when defining the path segments. Calls to BeginClipPath() must be balanced with calls to EndClip().

Example

IncludeFile "ProGUI_PB.pbi"

StartProGUI()

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

  ; Draw a red box partially clipped by a circle path
  DrawBox(50, 50, 200, 150, RGB(255, 0, 0), 0.5) ; Draw background box first

  ; Define a circular path
  PathMoveTo(150 + 75, 125) ; Start point for arc
  PathAddArc(150, 125, 75, 75, 0)
  PathAddArc(150 + 75, 125, 75, 75, 0)

  ; Set the clipping region to the defined path
  BeginClipPath()

  ; Draw a blue box - only the part inside the circle path will be visible
  DrawBox(50, 50, 200, 150, RGB(0, 0, 255), 1)

  ; Restore the previous clipping state
  EndClip()

  ; Draw text outside the clipped area (to show clipping is removed)
  DrawTxt(*UserData, 50, 220, RGB(0,0,0))
EndProcedure

MyWindow = CreateWindow(0, 0, 300, 300, "Path Clipping Example")
MyText = CreateText("Text outside clip", "Arial", 12)

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

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

FreeText(MyText)
StopProGUI()

Supported OS

Windows (Direct2D only)