MagnifyTransitionEffectLib — Plan9Basic Documentation

Overview

MagnifyTransitionEffectLib provides a dramatic zoom-based transition between two images, wrapping the FireMonkey TMagnifyTransitionEffect component. As the transition progresses, it zooms in on a configurable center point while revealing the target image — creating a cinematic "zoom into" reveal effect.

Property	Details
Library	`MagnifyTransitionEffectLib`
Prefix	`magnifytrans_`
Wraps	`TMagnifyTransitionEffect`
Functions	17
Type	Transition effect

Category	Count	Description
Creation / Destruction	2	Create and free effect
Progress	2	Get/set transition progress
Target Image	3	Set/get target bitmap, load from URL
Center Position	4	Get/set X and Y center of zoom
Effect Control	2	Enable/disable effect
Error Handling	4	Error codes and messages

🎬 Dramatic Reveals: This transition is perfect for dramatic focus effects — the camera "zooms into" a point on the source image and the target image is revealed as the zoom intensifies. Great for photo slideshows and cinematic applets.

Cross-Platform Support

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

Creation & Destruction

magnifytrans#(parent#)

Creates a new magnify 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

magnifytrans_free(effect#)

Destroys the effect and releases associated resources.

Parameter	Type	Description
`effect#`	Pointer	Effect handle to destroy

╯ create-magnify-transition.bas─◻✕
' Create a magnify transition
let trans# = magnifytrans#(img#)
magnifytrans_loadtarget#(trans#, "target.png")

' Clean up when done
magnifytrans_free(trans#)

Error Handling

All four standard error functions are available for detecting and diagnosing issues.

Function	Signature	Description
`magnifytrans_error()`	`magnifytrans_error@`	Returns last error code (0 = none)
`magnifytrans_errormsg$()`	`magnifytrans_errormsg$@`	Returns last error message
`magnifytrans_strerror$(code)`	`magnifytrans_strerror$@n`	Converts error code to text
`magnifytrans_clearerror()`	`magnifytrans_clearerror@`	Clears the error state

Code	Meaning
`0`	No error
`1`	Invalid effect handle
`2`	Invalid parameter value
`3`	Resource load failure

Progress

Controls how far the transition has advanced. At 0.0 the source image is fully visible; at 1.0 the target image is fully revealed after the zoom effect completes.

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

Value	Description
`0.0`	Source image fully visible
`0.25`	Beginning zoom — slight magnification
`0.5`	Mid-transition — zoom and reveal blending
`1.0`	Target image fully revealed

Target Image

The target image is revealed through the zoom transition. You can assign a bitmap directly or load from a URL or file path.

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

⚠ Target Required: Transition effects require a target image to work properly. Without a target, the effect will transition to a blank/black image. Always load or assign a target before animating.

Center Position

Controls the focal point of the zoom effect. The transition zooms toward this point as it progresses.

Function	Signature	Description
`magnifytrans_centerx#(effect#, value)`	`magnifytrans_centerx#@#n`	Sets X center (0.0–1.0)
`magnifytrans_centerx(effect#)`	`magnifytrans_centerx@#`	Gets X center
`magnifytrans_centery#(effect#, value)`	`magnifytrans_centery#@#n`	Sets Y center (0.0–1.0)
`magnifytrans_centery(effect#)`	`magnifytrans_centery@#`	Gets Y center

CenterX	CenterY	Zoom Focus
`0.5`	`0.5`	Center of image (default)
`0.0`	`0.0`	Zoom into top-left corner
`1.0`	`1.0`	Zoom into bottom-right corner
`0.25`	`0.25`	Zoom into upper-left area

🎯 Focus on Content: Set the center position to the most interesting part of the source image for the most dramatic effect. For example, center on a person's face or the main subject of a photo.

Effect Control

Enable or disable the transition effect at runtime without destroying it.

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

Complete Examples

Example 1: Basic Magnify Transition

╯ basic-magnify-transition.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let trans# = Pointer#(0)
let trkProg# = Pointer#(0)
let lblProg# = Pointer#(0)

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

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

' Create magnify transition effect
trans# = magnifytrans#(img#)
magnifytrans_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
  magnifytrans_progress#(trans#, p)
  label_text#(lblProg#, "Progress: " + stri$(p, 2))
endfunction

Example 2: Animated Zoom Transition

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

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

trans# = magnifytrans#(img#)
magnifytrans_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#, "Zoom!")
button_bounds#(btn#, 150, 210, 100, 30)
button_onclick#(btn#, "StartZoom")

form_show(frm#)

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

function Animate(sender#)
  progress = progress + 0.02
  magnifytrans_progress#(trans#, progress)

  if progress >= 1 then
    timer_enabled#(tmr#, 0)
    button_enabled#(btn#, 1)
  endif
endfunction

Example 3: Different Zoom Centers

╯ zoom-center-control.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let trans# = Pointer#(0)
let trkProg# = Pointer#(0)
let trkX# = Pointer#(0)
let trkY# = Pointer#(0)
let lblProg# = Pointer#(0)
let lblX# = Pointer#(0)
let lblY# = Pointer#(0)

frm# = form#("Zoom Center Control", 500, 500)

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

trans# = magnifytrans#(img#)
magnifytrans_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")

' X center control
lblX# = label#(frm#, "Center X: 0.50", 30, 260)
trkX# = trackbar#(frm#)
trackbar_bounds#(trkX#, 30, 285, 440, 25)
trackbar_max#(trkX#, 100)
trackbar_value#(trkX#, 50)
trackbar_onchange#(trkX#, "OnCenterX")

' Y center control
lblY# = label#(frm#, "Center Y: 0.50", 30, 330)
trkY# = trackbar#(frm#)
trackbar_bounds#(trkY#, 30, 355, 440, 25)
trackbar_max#(trkY#, 100)
trackbar_value#(trkY#, 50)
trackbar_onchange#(trkY#, "OnCenterY")

' Set initial progress
magnifytrans_progress#(trans#, 0.5)

form_show(frm#)

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

function OnCenterX(sender#) local x
  let x = trackbar_value(trkX#) / 100
  magnifytrans_centerx#(trans#, x)
  label_text#(lblX#, "Center X: " + stri$(x, 2))
endfunction

function OnCenterY(sender#) local y
  let y = trackbar_value(trkY#) / 100
  magnifytrans_centery#(trans#, y)
  label_text#(lblY#, "Center Y: " + stri$(y, 2))
endfunction

Best Practices

Practice	Why
Set center to the subject of interest	Creates a more purposeful, directed zoom effect
Use slower animation (0.01–0.02 steps)	Magnify transitions look best when not rushed
Match source and target image sizes	Prevents visual artifacts during the zoom blend
Load target before starting animation	Avoids blank frames during the transition
Disable controls during animation	Prevents interrupting the zoom sequence
Default center (0.5, 0.5) works well	Center zoom is the most natural-looking option

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`magnifytrans#(parent#)`	`magnifytrans#@#`	Create effect
`magnifytrans_free(effect#)`	`magnifytrans_free@#`	Destroy effect
PROGRESS
`magnifytrans_progress#(effect#, value)`	`magnifytrans_progress#@#n`	Set progress
`magnifytrans_progress(effect#)`	`magnifytrans_progress@#`	Get progress
TARGET IMAGE
`magnifytrans_target#(effect#, bitmap#)`	`magnifytrans_target#@##`	Set target bitmap
`magnifytrans_target#(effect#)`	`magnifytrans_target#@#`	Get target bitmap
`magnifytrans_loadtarget#(effect#, url$)`	`magnifytrans_loadtarget#@#$`	Load target from URL/file
CENTER POSITION
`magnifytrans_centerx#(effect#, value)`	`magnifytrans_centerx#@#n`	Set X center
`magnifytrans_centerx(effect#)`	`magnifytrans_centerx@#`	Get X center
`magnifytrans_centery#(effect#, value)`	`magnifytrans_centery#@#n`	Set Y center
`magnifytrans_centery(effect#)`	`magnifytrans_centery@#`	Get Y center
EFFECT CONTROL
`magnifytrans_enabled#(effect#, value)`	`magnifytrans_enabled#@#n`	Enable/disable
`magnifytrans_enabled(effect#)`	`magnifytrans_enabled@#`	Get enabled state
ERROR HANDLING
`magnifytrans_error()`	`magnifytrans_error@`	Last error code
`magnifytrans_errormsg$()`	`magnifytrans_errormsg$@`	Last error message
`magnifytrans_strerror$(code)`	`magnifytrans_strerror$@n`	Code to text
`magnifytrans_clearerror()`	`magnifytrans_clearerror@`	Clear error state

Library	Description
`MagnifyEffectLib`	Static magnifying glass effect
`CircleTransitionEffectLib`	Circular wipe transition
`BlurTransitionEffectLib`	Blur-based transition
`SmoothMagnifyEffectLib`	Smooth-edged magnification