MagnifyEffectLib — Plan9Basic Documentation

Overview

MagnifyEffectLib creates a magnifying glass effect on visual controls, wrapping the FireMonkey TMagnifyEffect component. A circular area around a configurable center point is enlarged, simulating looking through a magnifying lens. The zoom level, lens radius, and center position are all adjustable.

Property	Details
Library	`MagnifyEffectLib`
Prefix	`magnify_`
Wraps	`TMagnifyEffect`
Functions	18
Type	Visual effect (non-transition)

Category	Count	Description
Creation / Destruction	2	Create and free effect
Magnification	2	Get/set zoom level
Radius	2	Get/set lens radius
Center Position	4	Get/set X and Y center
Effect Control	4	Enabled and trigger get/set
Error Handling	4	Error codes and messages

🔍 Magnifying Lens: This effect is ideal for creating interactive image viewers, detail inspectors, or hover-zoom functionality in your applets. Move the center point to inspect different areas of an image.

Magnify vs SmoothMagnify

Plan9Basic offers two magnification effects. Choose the one that best fits your visual style:

Feature	MagnifyEffect	SmoothMagnifyEffect
Edge transition	Sharp boundary	Smooth, feathered edge
Visual style	Classic magnifying glass	Soft lens distortion
Parameters	4 (magnification, radius, center x/y)	6+ (adds inner/outer radius, aspect ratio)
Performance	Lighter	Slightly heavier
Best for	Simple zoom, image inspection	Polished UI, gradual lens effects

Cross-Platform Support

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

Creation & Destruction

magnify#(parent#)

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

magnify_free(effect#)

Destroys the effect and releases associated resources.

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

╯ create-magnify.bas─◻✕
' Create a magnifying glass effect
let mag# = magnify#(img#)
magnify_magnification#(mag#, 2)
magnify_radius#(mag#, 50)

' Clean up when done
magnify_free(mag#)

Error Handling

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

Function	Signature	Description
`magnify_error()`	`magnify_error@`	Returns last error code (0 = none)
`magnify_errormsg$()`	`magnify_errormsg$@`	Returns last error message
`magnify_strerror$(code)`	`magnify_strerror$@n`	Converts error code to text
`magnify_clearerror()`	`magnify_clearerror@`	Clears the error state

Code	Meaning
`0`	No error
`1`	Invalid effect handle
`2`	Invalid parameter value

Magnification

Controls the zoom level inside the magnifying lens area.

Function	Signature	Description
`magnify_magnification#(effect#, value)`	`magnify_magnification#@#n`	Sets zoom level
`magnify_magnification(effect#)`	`magnify_magnification@#`	Gets magnification

Value	Description	Use Case
`0.5`	Half size (shrink)	Fisheye / minification
`1.0`	No zoom (1:1)	No visible effect
`2.0`	2× zoom (default)	Standard magnification
`3.0–5.0`	High zoom	Detail inspection

🔎 Shrink Effect: Values below 1.0 create a shrinking/minification effect — the lens area shows a smaller version of the content. This can be used for creative distortion effects.

Radius

Controls the size of the magnifying lens in pixels.

Function	Signature	Description
`magnify_radius#(effect#, value)`	`magnify_radius#@#n`	Sets lens radius in pixels
`magnify_radius(effect#)`	`magnify_radius@#`	Gets radius

Value	Description
`10–30`	Small lens — precise detail inspection
`40–60`	Medium lens — general purpose
`80–100`	Large lens — broad area magnification

Center Position

Controls where the magnifying lens is positioned on the control. Values are normalized from 0.0 to 1.0.

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

CenterX	CenterY	Position
`0.0`	`0.0`	Top-left corner
`0.5`	`0.5`	Center (default)
`1.0`	`1.0`	Bottom-right corner
`0.0`	`1.0`	Bottom-left corner
`1.0`	`0.0`	Top-right corner

🎯 Normalized Coordinates: Center values are normalized (0–1), not pixel coordinates. CenterX 0 = left edge, 1 = right edge. CenterY 0 = top edge, 1 = bottom edge. This ensures consistent behavior regardless of image size.

Effect Control

Enable, disable, or trigger the magnify effect at runtime.

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

Complete Examples

Example 1: Basic Magnify Effect

╯ basic-magnify.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let mag# = Pointer#(0)

frm# = form#("Magnify Effect Demo", 400, 350)

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

' Create magnify effect
mag# = magnify#(img#)
magnify_magnification#(mag#, 2)
magnify_radius#(mag#, 50)

form_show(frm#)

Example 2: Adjustable Magnification

╯ adjustable-magnify.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let mag# = Pointer#(0)
let trkZoom# = Pointer#(0)
let trkRadius# = Pointer#(0)
let lblZoom# = Pointer#(0)
let lblRadius# = Pointer#(0)

frm# = form#("Magnify Control", 500, 450)

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

mag# = magnify#(img#)
magnify_magnification#(mag#, 2)
magnify_radius#(mag#, 40)

' Magnification slider (1-5x)
lblZoom# = label#(frm#, "Zoom: 2.0x", 30, 190)
trkZoom# = trackbar#(frm#)
trackbar_bounds#(trkZoom#, 30, 215, 440, 25)
trackbar_max#(trkZoom#, 50)
trackbar_value#(trkZoom#, 20)
trackbar_onchange#(trkZoom#, "OnZoom")

' Radius slider (10-100)
lblRadius# = label#(frm#, "Radius: 40", 30, 260)
trkRadius# = trackbar#(frm#)
trackbar_bounds#(trkRadius#, 30, 285, 440, 25)
trackbar_max#(trkRadius#, 100)
trackbar_value#(trkRadius#, 40)
trackbar_onchange#(trkRadius#, "OnRadius")

form_show(frm#)

function OnZoom(sender#) local z
  let z = trackbar_value(trkZoom#) / 10
  if z < 1 then
    z = 1
  endif
  magnify_magnification#(mag#, z)
  label_text#(lblZoom#, "Zoom: " + stri$(z, 1) + "x")
endfunction

function OnRadius(sender#) local r
  let r = trackbar_value(trkRadius#)
  if r < 10 then
    r = 10
  endif
  magnify_radius#(mag#, r)
  label_text#(lblRadius#, "Radius: " + str$(r))
endfunction

Example 3: Move Magnifier Position

╯ move-magnifier.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let mag# = Pointer#(0)
let trkX# = Pointer#(0)
let trkY# = Pointer#(0)
let lblX# = Pointer#(0)
let lblY# = Pointer#(0)

frm# = form#("Move Magnifier", 500, 470)

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

mag# = magnify#(img#)
magnify_magnification#(mag#, 2.5)
magnify_radius#(mag#, 35)

' X position slider
lblX# = label#(frm#, "Center X: 0.50", 30, 190)
trkX# = trackbar#(frm#)
trackbar_bounds#(trkX#, 30, 215, 440, 25)
trackbar_max#(trkX#, 100)
trackbar_value#(trkX#, 50)
trackbar_onchange#(trkX#, "OnMoveX")

' Y position slider
lblY# = label#(frm#, "Center Y: 0.50", 30, 260)
trkY# = trackbar#(frm#)
trackbar_bounds#(trkY#, 30, 285, 440, 25)
trackbar_max#(trkY#, 100)
trackbar_value#(trkY#, 50)
trackbar_onchange#(trkY#, "OnMoveY")

form_show(frm#)

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

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

Best Practices

Practice	Why
Use images with fine detail	Magnification is most useful when there is detail to reveal
Keep magnification between 1.5–3.0×	Higher values can cause pixelation with small source images
Scale radius to image size	A radius of 25–50% of the smaller image dimension works well
Clamp slider minimums	Prevents zero-radius or zero-magnification edge cases
Center defaults to 0.5, 0.5	Starts the lens in the center — intuitive for users
Combine with trackbars for interactivity	Lets users explore the image dynamically

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`magnify#(parent#)`	`magnify#@#`	Create effect
`magnify_free(effect#)`	`magnify_free@#`	Destroy effect
MAGNIFICATION
`magnify_magnification#(effect#, value)`	`magnify_magnification#@#n`	Set zoom level
`magnify_magnification(effect#)`	`magnify_magnification@#`	Get magnification
RADIUS
`magnify_radius#(effect#, value)`	`magnify_radius#@#n`	Set lens radius
`magnify_radius(effect#)`	`magnify_radius@#`	Get radius
CENTER POSITION
`magnify_centerx#(effect#, value)`	`magnify_centerx#@#n`	Set X center
`magnify_centerx(effect#)`	`magnify_centerx@#`	Get X center
`magnify_centery#(effect#, value)`	`magnify_centery#@#n`	Set Y center
`magnify_centery(effect#)`	`magnify_centery@#`	Get Y center
EFFECT CONTROL
`magnify_enabled#(effect#, value)`	`magnify_enabled#@#n`	Enable/disable
`magnify_enabled(effect#)`	`magnify_enabled@#`	Get enabled state
`magnify_trigger#(effect#, trigger$)`	`magnify_trigger#@#$`	Set trigger
`magnify_trigger$(effect#)`	`magnify_trigger$@#`	Get trigger
ERROR HANDLING
`magnify_error()`	`magnify_error@`	Last error code
`magnify_errormsg$()`	`magnify_errormsg$@`	Last error message
`magnify_strerror$(code)`	`magnify_strerror$@n`	Code to text
`magnify_clearerror()`	`magnify_clearerror@`	Clear error state

Library	Description
`SmoothMagnifyEffectLib`	Smooth-edged magnification effect
`MagnifyTransitionEffectLib`	Magnify-based transition effect
`PinchEffectLib`	Pinch/distortion effect