RippleTransitionEffectLib — Plan9Basic Documentation

Overview

RippleTransitionEffectLib creates a water-like ripple transition between a source and target image, wrapping the FireMonkey TRippleTransitionEffect component. As the transition progresses, concentric ripple waves distort the source image while the target image emerges through the distortion — like dropping a stone into a pond that reveals a new scene beneath the surface.

Property	Details
Library	`RippleTransitionEffectLib`
Prefix	`rippletrans_`
Wraps	`TRippleTransitionEffect`
Functions	13
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
Effect Control	2	Enabled get/set
Error Handling	4	Error codes and messages

💧 Water Drop Transition: This is one of the most visually appealing transition effects — ideal for presentations, photo galleries, and creative scene changes. The ripple distortion adds organic, fluid motion that feels natural and eye-catching.

Cross-Platform Support

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

Creation & Destruction

rippletrans#(parent#)

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

Parameter	Type	Description
`parent#`	Pointer	Target visual control (e.g., image)
Returns	Pointer	Effect handle, or 0 on failure

rippletrans_free(effect#)

Destroys the effect and releases associated resources.

Error Handling

Function	Signature	Description
`rippletrans_error()`	`rippletrans_error@`	Returns last error code (0 = none)
`rippletrans_errormsg$()`	`rippletrans_errormsg$@`	Returns last error message
`rippletrans_strerror$(code)`	`rippletrans_strerror$@n`	Converts error code to text
`rippletrans_clearerror()`	`rippletrans_clearerror@`	Clears the error state

Target Image

The target image is what the transition reveals through the ripple distortion. You can set it from an existing bitmap pointer or load it directly from a URL or file path.

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

⚠ Target Required: Transition effects need a target image to work properly. Without a target, the transition has nothing to reveal. Always call rippletrans_loadtarget# or rippletrans_target# before animating.

Progress

Controls the transition state between source (0.0) and target (1.0) images.

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

Value	Visual State
`0.0`	Source image (no distortion)
`0.25`	Ripples begin forming on source
`0.5`	Peak ripple distortion (midpoint)
`0.75`	Target image emerging through ripples
`1.0`	Target image (fully resolved)

Effect Control

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

Complete Examples

Example 1: Slider-Controlled Transition

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

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

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

' Create ripple transition effect
trans# = rippletrans#(img#)
rippletrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")

' Progress slider
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
  rippletrans_progress#(trans#, p)
  label_text#(lblProg#, "Progress: " + stri$(p, 2))
endfunction

Example 2: Animated Ripple Transition

╯ animated-rippletrans.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 Ripple Transition", 400, 350)

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

trans# = rippletrans#(img#)
rippletrans_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#, "Ripple!")
button_bounds#(btn#, 150, 210, 100, 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
  rippletrans_progress#(trans#, progress)
  
  if progress >= 1 then
    timer_enabled#(tmr#, 0)
    button_enabled#(btn#, 1)
  endif
endfunction

Example 3: Toggle Effect

╯ toggle-rippletrans.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let trans# = Pointer#(0)
let btn# = Pointer#(0)
let isOn = 1

frm# = form#("Toggle Ripple Transition", 400, 350)

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

trans# = rippletrans#(img#)
rippletrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")
rippletrans_progress#(trans#, 0.5)

btn# = button#(frm#, "Disable Effect")
button_bounds#(btn#, 130, 210, 140, 30)
button_onclick#(btn#, "Toggle")

form_show(frm#)

function Toggle(sender#)
  if isOn = 1 then
    rippletrans_enabled#(trans#, 0)
    isOn = 0
    button_text#(btn#, "Enable Effect")
  else
    rippletrans_enabled#(trans#, 1)
    isOn = 1
    button_text#(btn#, "Disable Effect")
  endif
endfunction

Best Practices

Practice	Why
Always load a target image before animating	Transitions need a target to reveal
Use timer with 20–40ms interval	~30ms gives smooth ~33 FPS animation
Increment progress by 0.01–0.03 per tick	Slower steps = more visible ripple effect
Disable button during animation	Prevents re-triggering mid-transition
Match source and target dimensions	Ensures clean transition without scaling
Pair with RippleEffectLib for consistent style	Use static ripples on other elements for thematic consistency

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`rippletrans#(parent#)`	`rippletrans#@#`	Create effect
`rippletrans_free(effect#)`	`rippletrans_free@#`	Destroy effect
TARGET IMAGE
`rippletrans_target#(effect#, bitmap#)`	`rippletrans_target#@##`	Set target bitmap
`rippletrans_target#(effect#)`	`rippletrans_target#@#`	Get target bitmap
`rippletrans_loadtarget#(effect#, url$)`	`rippletrans_loadtarget#@#$`	Load target from URL/file
PROGRESS
`rippletrans_progress#(effect#, value)`	`rippletrans_progress#@#n`	Set progress (0–1)
`rippletrans_progress(effect#)`	`rippletrans_progress@#`	Get progress
EFFECT CONTROL
`rippletrans_enabled#(effect#, value)`	`rippletrans_enabled#@#n`	Enable/disable
`rippletrans_enabled(effect#)`	`rippletrans_enabled@#`	Get enabled state
ERROR HANDLING
`rippletrans_error()`	`rippletrans_error@`	Last error code
`rippletrans_errormsg$()`	`rippletrans_errormsg$@`	Last error message
`rippletrans_strerror$(code)`	`rippletrans_strerror$@n`	Code to text
`rippletrans_clearerror()`	`rippletrans_clearerror@`	Clear error state

Library	Description
`RippleEffectLib`	Static/animated ripple distortion
`WaterTransitionEffectLib`	Water-drop transition
`WaveTransitionEffectLib`	Wave-based transition
`SwirlTransitionEffectLib`	Swirl-based transition