DropTransitionEffectLib — Plan9Basic Documentation

DropTransitionEffectLib — Drop Transition

Vertical columns of the target image drop down to replace the source image, creating a “falling tiles” or “slot machine” style transition. Wraps FireMonkey’s TDropTransitionEffect. Each column drops at a different time determined by the random seed, producing a staggered, mechanical reveal. 15 functions.

Category	Count	Description
Error Handling	4	droptrans_error, errormsg$, strerror$, clearerror
Creation & Destruction	2	droptrans# (create), droptrans_free (destroy)
Target Image	3	target (get/set), loadtarget
Progress & Seed	4	progress, randomseed (get/set)
Effect Control	2	enabled (get/set)

⚠ Target Required: Transition effects need a target image to transition to. Without a target, columns drop to reveal transparent/empty space.

How Drop Transition Works

The image is divided into vertical columns. As progress increases, columns of the target image slide down from the top to cover the source, each column dropping at a different speed controlled by the random seed.

╯ drop-visual─◻✕
Progress = 0.0        Progress = 0.4        Progress = 1.0
+--+--+--+--+--+     +--+--+--+--+--+     +--+--+--+--+--+
|  SOURCE IMAGE |     |TT|  |TT|  |TT|     |             |
|               |     |TT|  |TT|  |TT|     |   TARGET    |
|               |     |SS|SS|SS|SS|SS|     |   IMAGE     |
|               |     |SS|SS|SS|SS|SS|     |             |
+--+--+--+--+--+     +--+--+--+--+--+     +--+--+--+--+--+
                      T=Target S=Source

Progress	What You See
0.0	100% source — no columns have dropped
0.25	Some columns begin dropping from the top
0.5	Staggered drop — columns at various heights
0.75	Most columns have landed, a few still falling
1.0	100% target — all columns fully dropped

Cross-Platform Support

Platform	Status	Notes
Windows	✅ Full Support	GPU-accelerated via Direct2D
Linux	✅ Full Support	Software rendering fallback
Android	✅ Full Support	GPU-accelerated

Error Handling

Function	Signature	Description
`droptrans_error()`	`droptrans_error@`	Returns last error code (0 = no error)
`droptrans_errormsg$()`	`droptrans_errormsg$@`	Returns last error message as string
`droptrans_strerror$(code)`	`droptrans_strerror$@n`	Converts an error code to descriptive text
`droptrans_clearerror()`	`droptrans_clearerror@`	Clears the error state

Error Codes

Code	Constant	Meaning
0	ERR_NONE	No error
1	ERR_NIL_EFFECT	Effect pointer is nil
2	ERR_INVALID_EFFECT	Pointer is not a valid TDropTransitionEffect
3	ERR_INVALID_VALUE	Property value out of range
4	ERR_NIL_PARENT	Parent control pointer is nil
5	ERR_INVALID_PARENT	Pointer is not a valid TFmxObject

Creation & Destruction

Function	Signature	Description
`droptrans#(parent#)`	`droptrans#@#`	Creates a drop transition effect on the given control. Returns the effect pointer.
`droptrans_free(effect#)`	`droptrans_free@#`	Destroys the effect and removes it from the parent.

Target Image

Function	Signature	Description
`droptrans_target#(effect#, bitmap#)`	`droptrans_target#@##`	Sets the target bitmap pointer directly
`droptrans_target#(effect#)`	`droptrans_target#@#`	Gets the current target bitmap pointer
`droptrans_loadtarget#(effect#, url$)`	`droptrans_loadtarget#@#$`	Loads the target image from a URL or file path

Progress

Function	Signature	Description
`droptrans_progress#(effect#, value)`	`droptrans_progress#@#n`	Sets progress (0.0–1.0)
`droptrans_progress(effect#)`	`droptrans_progress@#`	Gets current progress

Random Seed

Controls the drop timing pattern. Different seeds cause columns to start dropping at different times, changing the stagger pattern. Set before animating for consistent results.

Function	Signature	Description
`droptrans_randomseed#(effect#, value)`	`droptrans_randomseed#@#n`	Sets random seed (0.0–1.0)
`droptrans_randomseed(effect#)`	`droptrans_randomseed@#`	Gets current seed

Effect Control

Function	Signature	Description
`droptrans_enabled#(effect#, value)`	`droptrans_enabled#@#n`	Enables (1) or disables (0)
`droptrans_enabled(effect#)`	`droptrans_enabled@#`	Gets enabled state

Complete Examples

Slider-Controlled Drop

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

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

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

trans# = droptrans#(img#)
droptrans_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
  droptrans_progress#(trans#, p)
  label_text#(lblProg#, "Progress: " + stri$(p, 2))
endfunction

Animated Drop with Timer

╯ drop-animated.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 Drop", 400, 350)

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

trans# = droptrans#(img#)
droptrans_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#, "Drop!")
button_bounds#(btn#, 150, 210, 100, 30)
button_onclick#(btn#, "StartDrop")

form_show(frm#)

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

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

Dual Sliders — Progress + Random Seed

╯ drop-patterns.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let trans# = Pointer#(0)
let trkProg# = Pointer#(0)
let trkSeed# = Pointer#(0)
let lblProg# = Pointer#(0)
let lblSeed# = Pointer#(0)

frm# = form#("Drop Patterns", 500, 420)

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

trans# = droptrans#(img#)
droptrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")
droptrans_progress#(trans#, 0.5)

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")

lblSeed# = label#(frm#, "Random Seed: 0.00", 30, 260)
trkSeed# = trackbar#(frm#)
trackbar_bounds#(trkSeed#, 30, 285, 440, 25)
trackbar_max#(trkSeed#, 100)
trackbar_value#(trkSeed#, 0)
trackbar_onchange#(trkSeed#, "OnSeed")

form_show(frm#)

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

function OnSeed(sender#) local s
  let s = trackbar_value(trkSeed#) / 100
  droptrans_randomseed#(trans#, s)
  label_text#(lblSeed#, "Random Seed: " + stri$(s, 2))
endfunction

Best Practices

Practice	Why
Always load a target image before animating	Without a target, columns drop to reveal nothing
Set random seed before starting animation	Changing seed mid-drop produces jarring column jumps
Use slower step (0.01) for dramatic stagger	Slower reveals the column-by-column pattern better
Use faster step (0.03–0.05) for snappy transitions	Quick slot-machine feel for UI changes
Try many different seeds for variety	Each seed creates a unique column-drop timing
Combine with `BlindTransitionEffectLib`	Both use columns; blinds reveal horizontally, drop vertically
Good for game UIs and scoreboards	Slot-machine feel fits games, leaderboards, and reveals
Disable button during animation	Prevents overlapping transitions

Quick Reference

Function	Signature	Description
ERROR HANDLING
`droptrans_error()`	`droptrans_error@`	Last error code
`droptrans_errormsg$()`	`droptrans_errormsg$@`	Last error message
`droptrans_strerror$(code)`	`droptrans_strerror$@n`	Error code to text
`droptrans_clearerror()`	`droptrans_clearerror@`	Clear error state
CREATION & DESTRUCTION
`droptrans#(parent#)`	`droptrans#@#`	Create effect on control
`droptrans_free(effect#)`	`droptrans_free@#`	Destroy effect
TARGET IMAGE
`droptrans_target#(effect#, bmp#)`	`droptrans_target#@##`	Set target bitmap
`droptrans_target#(effect#)`	`droptrans_target#@#`	Get target bitmap
`droptrans_loadtarget#(effect#, url$)`	`droptrans_loadtarget#@#$`	Load target from URL/file
PROGRESS & SEED
`droptrans_progress#(effect#, val)`	`droptrans_progress#@#n`	Set progress (0.0–1.0)
`droptrans_progress(effect#)`	`droptrans_progress@#`	Get progress
`droptrans_randomseed#(effect#, val)`	`droptrans_randomseed#@#n`	Set seed (0.0–1.0)
`droptrans_randomseed(effect#)`	`droptrans_randomseed@#`	Get seed
EFFECT CONTROL
`droptrans_enabled#(effect#, val)`	`droptrans_enabled#@#n`	Enable (1) / disable (0)
`droptrans_enabled(effect#)`	`droptrans_enabled@#`	Get enabled state

15 functions. Part of the Plan9Basic transition effects library system.