ShapeTransitionEffectLib — Plan9Basic Documentation

Overview

ShapeTransitionEffectLib uses geometric shapes to reveal the target image through the source, wrapping the FireMonkey TShapeTransitionEffect component. As progress advances, geometric patterns expand or contract to reveal the target — creating a dynamic, presentation-style transition.

Property	Details
Library	`ShapeTransitionEffectLib`
Prefix	`shapetrans_`
Wraps	`TShapeTransitionEffect`
Functions	15
Type	Transition effect

Category	Count	Description
Creation / Destruction	2	Create and free effect
Target Image	3	Set/get/load target bitmap
Progress	2	Get/set transition progress
Random Seed	2	Get/set shape pattern variation
Effect Control	2	Enabled get/set
Error Handling	4	Error codes and messages

◆ Geometric Patterns: Shape transitions are classic presentation effects — geometric forms expand across the image to reveal the next scene. Change the RandomSeed to get different shape arrangements each time.

Cross-Platform Support

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

Creation & Destruction

shapetrans#(parent#)

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

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

shapetrans_free(effect#)

Destroys the effect and releases associated resources.

Error Handling

Function	Signature	Description
`shapetrans_error()`	`shapetrans_error@`	Returns last error code (0 = none)
`shapetrans_errormsg$()`	`shapetrans_errormsg$@`	Returns last error message
`shapetrans_strerror$(code)`	`shapetrans_strerror$@n`	Converts error code to text
`shapetrans_clearerror()`	`shapetrans_clearerror@`	Clears the error state

Target Image

Function	Signature	Description
`shapetrans_target#(effect#, bitmap#)`	`shapetrans_target#@##`	Sets target from bitmap pointer
`shapetrans_target#(effect#)`	`shapetrans_target#@#`	Gets target bitmap pointer
`shapetrans_loadtarget#(effect#, url$)`	`shapetrans_loadtarget#@#$`	Loads target from URL or file

⚠ Target Required: Always load a target image before animating progress.

Progress

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

Random Seed

Controls the shape pattern variation. Different seed values produce different geometric arrangements.

Function	Signature	Description
`shapetrans_randomseed#(effect#, value)`	`shapetrans_randomseed#@#n`	Set random seed
`shapetrans_randomseed(effect#)`	`shapetrans_randomseed@#`	Get random seed

Effect Control

Function	Signature	Description
`shapetrans_enabled#(effect#, value)`	`shapetrans_enabled#@#n`	Enable (1) or disable (0)
`shapetrans_enabled(effect#)`	`shapetrans_enabled@#`	Gets enabled state

Complete Examples

Example 1: Slider-Controlled Transition

╯ shape-slider.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let trans# = Pointer#(0)
let trkProg# = Pointer#(0)
let lblProg# = Pointer#(0)

frm# = form#("Shape Transition", 450, 400)

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

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

lblProg# = label#(frm#, "Progress: 0.00", 50, 200)
trkProg# = trackbar#(frm#)
trackbar_bounds#(trkProg#, 50, 230, 350, 30)
trackbar_max#(trkProg#, 100)
trackbar_value#(trkProg#, 0)
trackbar_onchange#(trkProg#, "OnProgress")

form_show(frm#)

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

Example 2: Animated Transition

╯ animated-shape.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#("Animated Shape Transition", 400, 350)

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

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

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

btn# = button#(frm#, "Transition!")
button_bounds#(btn#, 140, 210, 120, 30)
button_onclick#(btn#, "StartTransition")

form_show(frm#)

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

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

Example 3: Random Seed Variation

╯ shape-seed.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let trans# = Pointer#(0)
let trkSeed# = Pointer#(0)
let lblSeed# = Pointer#(0)

frm# = form#("Shape Pattern Variation", 450, 400)

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

trans# = shapetrans#(img#)
shapetrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")
shapetrans_progress#(trans#, 0.5)

lblSeed# = label#(frm#, "Random Seed: 0", 50, 200)
trkSeed# = trackbar#(frm#)
trackbar_bounds#(trkSeed#, 50, 230, 350, 30)
trackbar_max#(trkSeed#, 100)
trackbar_value#(trkSeed#, 0)
trackbar_onchange#(trkSeed#, "OnSeed")

form_show(frm#)

function OnSeed(sender#) local s
  let s = trackbar_value(trkSeed#)
  shapetrans_randomseed#(trans#, s)
  label_text#(lblSeed#, "Random Seed: " + str$(s))
endfunction

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`shapetrans#(parent#)`	`shapetrans#@#`	Create effect
`shapetrans_free(effect#)`	`shapetrans_free@#`	Destroy effect
TARGET IMAGE
`shapetrans_target#(effect#, bitmap#)`	`shapetrans_target#@##`	Set target bitmap
`shapetrans_target#(effect#)`	`shapetrans_target#@#`	Get target bitmap
`shapetrans_loadtarget#(effect#, url$)`	`shapetrans_loadtarget#@#$`	Load target
PROGRESS
`shapetrans_progress#(effect#, value)`	`shapetrans_progress#@#n`	Set progress (0–1)
`shapetrans_progress(effect#)`	`shapetrans_progress@#`	Get progress
RANDOM SEED
`shapetrans_randomseed#(effect#, value)`	`shapetrans_randomseed#@#n`	Set pattern seed
`shapetrans_randomseed(effect#)`	`shapetrans_randomseed@#`	Get seed value
EFFECT CONTROL
`shapetrans_enabled#(effect#, value)`	`shapetrans_enabled#@#n`	Enable/disable
`shapetrans_enabled(effect#)`	`shapetrans_enabled@#`	Get enabled state
ERROR HANDLING
`shapetrans_error()`	`shapetrans_error@`	Last error code
`shapetrans_errormsg$()`	`shapetrans_errormsg$@`	Last error message
`shapetrans_strerror$(code)`	`shapetrans_strerror$@n`	Code to text
`shapetrans_clearerror()`	`shapetrans_clearerror@`	Clear error state

Library	Description
`CircleTransitionEffectLib`	Circle-based transition
`BlindTransitionEffectLib`	Blind/stripe transition
`DissolveTransitionEffectLib`	Random pixel dissolve