CircleTransitionEffectLib — Plan9Basic Documentation

Overview

CircleTransitionEffectLib reveals the target image through an expanding or contracting circle, wrapping the FireMonkey TCircleTransitionEffect component. Creates the classic "iris wipe" transition commonly seen in old movies, cartoons, and video editing.

Property	Details
Library	`CircleTransitionEffectLib`
Prefix	`circletrans_`
Wraps	`TCircleTransitionEffect`
Functions	20
Type	Transition effect

Category	Count	Description
Creation / Destruction	2	Create and free effect
Target Image	4	Set/get/load target bitmap
Progress	2	Get/set transition progress
Circle Parameters	4	Fuzzy edge and circle size
Effect Control	4	Enabled and trigger get/set
Error Handling	4	Error codes and messages

🎥 Iris Wipe: A circle expands from the center to reveal the target image. Control the edge softness with FuzzyAmount (0 = hard edge, 1 = very soft) and the overall size with CircleSize. Classic Looney Tunes "That's all, folks!" effect!

Cross-Platform Support

Platform	Support
Windows	✅ Full support
Linux	✅ Full support
Android	✅ Full support

Creation & Destruction

circletrans#(parent#)

Creates a new circle transition effect attached to the specified visual control.

Parameter	Type	Description
`parent#`	Pointer	Target visual control
Returns	Pointer	Effect handle, or 0 on failure

circletrans_free(effect#)

Destroys the effect and releases associated resources.

Error Handling

Function	Signature	Description
`circletrans_error()`	`circletrans_error@`	Returns last error code (0 = none)
`circletrans_errormsg$()`	`circletrans_errormsg$@`	Returns last error message
`circletrans_strerror$(code)`	`circletrans_strerror$@n`	Converts error code to text
`circletrans_clearerror()`	`circletrans_clearerror@`	Clears the error state

Target Image

Function	Signature	Description
`circletrans_target#(effect#, bitmap#)`	`circletrans_target#@##`	Sets target from bitmap pointer
`circletrans_target#(effect#)`	`circletrans_target#@#`	Gets target bitmap pointer
`circletrans_loadtarget#(effect#, url$)`	`circletrans_loadtarget#@#$`	Loads target from URL or file
`circletrans_targetfromimage#(effect#, image#)`	`circletrans_targetfromimage#@##`	Copies target from TImage control

⚠ Target Required: Always load a target image before animating progress. Without a target, the effect transitions to transparent.

Progress

Function	Signature	Description
`circletrans_progress#(effect#, value)`	`circletrans_progress#@#n`	Set progress (0.0–1.0)
`circletrans_progress(effect#)`	`circletrans_progress@#`	Get current progress

At 0 the source is fully visible. At 1 the target is fully revealed through the expanding circle.

Circle Parameters

Function	Signature	Description
`circletrans_fuzzy#(effect#, value)`	`circletrans_fuzzy#@#n`	Set edge softness (0–1)
`circletrans_fuzzy(effect#)`	`circletrans_fuzzy@#`	Get fuzzy amount
`circletrans_circlesize#(effect#, value)`	`circletrans_circlesize#@#n`	Set circle size factor (0–2)
`circletrans_circlesize(effect#)`	`circletrans_circlesize@#`	Get circle size

Property	Default	Range	Description
FuzzyAmount	`0.1`	0–1	0 = hard crisp edge, 1 = very soft feathered edge
CircleSize	`1.0`	0–2	<1 = smaller circle, >1 = larger circle

Effect Control

Function	Signature	Description
`circletrans_enabled#(effect#, value)`	`circletrans_enabled#@#n`	Enable (1) or disable (0)
`circletrans_enabled(effect#)`	`circletrans_enabled@#`	Gets enabled state
`circletrans_trigger#(effect#, trigger$)`	`circletrans_trigger#@#$`	Sets trigger string
`circletrans_trigger$(effect#)`	`circletrans_trigger$@#`	Gets trigger string

Complete Examples

Example 1: Animated Iris Wipe

╯ circle-wipe.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let trans# = Pointer#(0)
let tmr# = Pointer#(0)
let btn# = Pointer#(0)
let progress = 0

frm# = form#("Circle Wipe Animation", 400, 350)

img# = image#(frm#)
image_bounds#(img#, 100, 30, 200, 150)
image_load#(img#, "https://picsum.photos/200/150?random=1")

trans# = circletrans#(img#)
circletrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")
circletrans_fuzzy#(trans#, 0.05)

tmr# = timer#()
timer_interval#(tmr#, 30)
timer_enabled#(tmr#, 0)
timer_ontimer#(tmr#, "Animate")

btn# = button#(frm#, "Start Wipe")
button_bounds#(btn#, 150, 210, 100, 30)
button_onclick#(btn#, "StartWipe")

form_show(frm#)

function StartWipe(sender#)
  progress = 0
  timer_enabled#(tmr#, 1)
  button_enabled#(btn#, 0)
endfunction

function Animate(sender#)
  progress = progress + 0.02
  circletrans_progress#(trans#, progress)
  
  if progress >= 1 then
    timer_enabled#(tmr#, 0)
    button_enabled#(btn#, 1)
  endif
endfunction

Example 2: Adjustable Circle Parameters

╯ circle-params.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let trans# = Pointer#(0)
let trkProg# = Pointer#(0)
let trkFuzzy# = Pointer#(0)
let trkSize# = Pointer#(0)
let lblProg# = Pointer#(0)
let lblFuzzy# = Pointer#(0)
let lblSize# = Pointer#(0)

frm# = form#("Circle Parameters", 500, 450)

img# = image#(frm#)
image_bounds#(img#, 150, 20, 200, 150)
image_load#(img#, "https://picsum.photos/200/150?random=1")

trans# = circletrans#(img#)
circletrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")

' Progress control
lblProg# = label#(frm#, "Progress: 0.50", 30, 190)
trkProg# = trackbar#(frm#)
trackbar_bounds#(trkProg#, 30, 215, 440, 25)
trackbar_max#(trkProg#, 100)
trackbar_value#(trkProg#, 50)
trackbar_onchange#(trkProg#, "OnProgress")

' Fuzzy control
lblFuzzy# = label#(frm#, "Fuzzy: 0.10", 30, 255)
trkFuzzy# = trackbar#(frm#)
trackbar_bounds#(trkFuzzy#, 30, 280, 440, 25)
trackbar_max#(trkFuzzy#, 100)
trackbar_value#(trkFuzzy#, 10)
trackbar_onchange#(trkFuzzy#, "OnFuzzy")

' Circle size control
lblSize# = label#(frm#, "Size: 1.00", 30, 320)
trkSize# = trackbar#(frm#)
trackbar_bounds#(trkSize#, 30, 345, 440, 25)
trackbar_max#(trkSize#, 200)
trackbar_value#(trkSize#, 100)
trackbar_onchange#(trkSize#, "OnSize")

circletrans_progress#(trans#, 0.5)

form_show(frm#)

function OnProgress(sender#) local p
  let p = trackbar_value(trkProg#) / 100
  circletrans_progress#(trans#, p)
  label_text#(lblProg#, "Progress: " + stri$(p, 2))
endfunction

function OnFuzzy(sender#) local f
  let f = trackbar_value(trkFuzzy#) / 100
  circletrans_fuzzy#(trans#, f)
  label_text#(lblFuzzy#, "Fuzzy: " + stri$(f, 2))
endfunction

function OnSize(sender#) local s
  let s = trackbar_value(trkSize#) / 100
  circletrans_circlesize#(trans#, s)
  label_text#(lblSize#, "Size: " + stri$(s, 2))
endfunction

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`circletrans#(parent#)`	`circletrans#@#`	Create effect
`circletrans_free(effect#)`	`circletrans_free@#`	Destroy effect
TARGET IMAGE
`circletrans_target#(effect#, bitmap#)`	`circletrans_target#@##`	Set target bitmap
`circletrans_target#(effect#)`	`circletrans_target#@#`	Get target bitmap
`circletrans_loadtarget#(effect#, url$)`	`circletrans_loadtarget#@#$`	Load target
`circletrans_targetfromimage#(effect#, image#)`	`circletrans_targetfromimage#@##`	Target from image
PROGRESS
`circletrans_progress#(effect#, value)`	`circletrans_progress#@#n`	Set progress (0–1)
`circletrans_progress(effect#)`	`circletrans_progress@#`	Get progress
CIRCLE PARAMETERS
`circletrans_fuzzy#(effect#, value)`	`circletrans_fuzzy#@#n`	Set edge softness (0–1)
`circletrans_fuzzy(effect#)`	`circletrans_fuzzy@#`	Get fuzzy amount
`circletrans_circlesize#(effect#, value)`	`circletrans_circlesize#@#n`	Set circle size (0–2)
`circletrans_circlesize(effect#)`	`circletrans_circlesize@#`	Get circle size
EFFECT CONTROL
`circletrans_enabled#(effect#, value)`	`circletrans_enabled#@#n`	Enable/disable
`circletrans_enabled(effect#)`	`circletrans_enabled@#`	Get enabled state
`circletrans_trigger#(effect#, trigger$)`	`circletrans_trigger#@#$`	Set trigger
`circletrans_trigger$(effect#)`	`circletrans_trigger$@#`	Get trigger
ERROR HANDLING
`circletrans_error()`	`circletrans_error@`	Last error code
`circletrans_errormsg$()`	`circletrans_errormsg$@`	Last error message
`circletrans_strerror$(code)`	`circletrans_strerror$@n`	Code to text
`circletrans_clearerror()`	`circletrans_clearerror@`	Clear error state

Library	Description
`DissolveTransitionEffectLib`	Pixel dissolve transition
`BlindTransitionEffectLib`	Blinds/venetian transition
`FadeTransitionEffectLib`	Simple fade transition