BeginClipBox - ProGUI Reference Manual

Syntax

BeginClipBox(x.d, y.d, Width.d, Height.d)

Description

Sets a rectangular clipping region for subsequent drawing operations within the current drawing context. Any drawing that occurs outside this rectangle will be clipped (not rendered). Clipping regions are cumulative; nested calls will result in an intersection of the clipping areas. Each call to BeginClipBox() must be paired with a corresponding call to EndClip().

Parameters

x.d
The horizontal coordinate of the top-left corner of the clipping rectangle in device-independent pixels (DIPs) relative to the current drawing context's origin.

y.d
The vertical coordinate of the top-left corner of the clipping rectangle in DIPs relative to the current drawing context's origin.

Width.d
The width of the clipping rectangle in DIPs.

Height.d
The height of the clipping rectangle in DIPs.

Return Value

This command does not return a value.

Remarks

The coordinates and dimensions are specified in DIPs but are converted internally to physical pixels based on the current output's DPI scaling. The clipping rectangle is aligned to the pixel grid. Clipping is applied after the current transformation. Calls to BeginClipBox() must be balanced with calls to EndClip() to restore the previous clipping state.

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
  DrawBox(50, 50, 200, 150, RGB(255, 0, 0), 0.5) ; Draw background box first

  ; Set a clipping region
  BeginClipBox(100, 80, 100, 100)

  ; Draw a blue box - only the part inside the clip region 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, "Clipping Example")
MyText = CreateText("Text outside clip", "Arial", 12)

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

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

FreeText(MyText)
StopProGUI()

Supported OS

Windows, Linux