ShadowEffectLib — Plan9Basic Documentation

Overview

ShadowEffectLib creates drop shadow effects for visual controls, wrapping the FireMonkey TShadowEffect component. Shadows add depth and visual hierarchy to UI elements — configurable with distance, direction, softness, opacity, and color for professional-quality results.

Property	Details
Library	`ShadowEffectLib`
Prefix	`shadow_`
Wraps	`TShadowEffect`
Functions	20
Type	Visual effect (decorative)

Category	Count	Description
Creation / Destruction	2	Create and free effect
Distance	2	Get/set shadow offset
Direction	2	Get/set light angle
Softness	2	Get/set blur amount
Opacity	2	Get/set transparency
Color	2	Get/set shadow color
Effect Control	4	Enabled and trigger get/set
Error Handling	4	Error codes and messages

👁 Depth & Hierarchy: Drop shadows are one of the most fundamental UI design tools. They suggest elevation — a control with a shadow appears to "float" above the background, drawing the user's attention and creating a clear visual hierarchy.

Cross-Platform Support

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

Creation & Destruction

shadow#(parent#)

Creates a new shadow effect attached to the specified visual control.

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

shadow_free(effect#)

Destroys the effect and releases associated resources.

Error Handling

Function	Signature	Description
`shadow_error()`	`shadow_error@`	Returns last error code (0 = none)
`shadow_errormsg$()`	`shadow_errormsg$@`	Returns last error message
`shadow_strerror$(code)`	`shadow_strerror$@n`	Converts error code to text
`shadow_clearerror()`	`shadow_clearerror@`	Clears the error state

Distance

Controls the offset of the shadow from the control in pixels. Larger distance = element appears higher above the surface.

Function	Signature	Description
`shadow_distance#(effect#, value)`	`shadow_distance#@#n`	Set offset (0–50 pixels)
`shadow_distance(effect#)`	`shadow_distance@#`	Get distance

Value	Appearance	Use Case
`1–3`	Subtle, close shadow	Cards, subtle elevation
`4–8`	Medium elevation	Buttons, dialogs
`10–20`	High floating	Popups, modals
`25–50`	Very dramatic	Artistic/dramatic effects

Direction

Sets the angle of the light source in degrees (0–360). The shadow appears on the opposite side of the light.

Function	Signature	Description
`shadow_direction#(effect#, degrees)`	`shadow_direction#@#n`	Set light angle (0–360)
`shadow_direction(effect#)`	`shadow_direction@#`	Get direction

Angle	Light Position	Shadow Falls
`45`	Top-right (default)	Bottom-left
`90`	Top	Bottom
`135`	Top-left	Bottom-right
`180`	Left	Right
`225`	Bottom-left	Top-right
`270`	Bottom	Top
`315`	Bottom-right	Top-left

Softness

Controls the blur amount of the shadow. Higher values create softer, more diffuse shadows.

Function	Signature	Description
`shadow_softness#(effect#, value)`	`shadow_softness#@#n`	Set blur (0–1)
`shadow_softness(effect#)`	`shadow_softness@#`	Get softness

Opacity

Controls the transparency of the shadow. Lower values create more subtle shadows.

Function	Signature	Description
`shadow_opacity#(effect#, value)`	`shadow_opacity#@#n`	Set opacity (0–1)
`shadow_opacity(effect#)`	`shadow_opacity@#`	Get opacity

Color

Sets the color of the shadow. Defaults to black, but colored shadows can create interesting effects.

Function	Signature	Description
`shadow_color#(effect#, color$)`	`shadow_color#@#$`	Set shadow color (name or hex)
`shadow_color(effect#)`	`shadow_color@#`	Get color as number

Effect Control

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

Complete Examples

Example 1: Basic Shadow

╯ basic-shadow.bas─◻✕
let frm# = Pointer#(0)
let rect# = Pointer#(0)
let sh# = Pointer#(0)

frm# = form#("Shadow Demo", 400, 300)

rect# = rectangle#(frm#)
rectangle_bounds#(rect#, 100, 80, 200, 120)
rectangle_fill#(rect#, "White")

sh# = shadow#(rect#)
shadow_distance#(sh#, 5)
shadow_direction#(sh#, 45)
shadow_softness#(sh#, 0.4)
shadow_opacity#(sh#, 0.5)

form_show(frm#)

Example 2: Adjustable Distance

╯ shadow-distance.bas─◻✕
let frm# = Pointer#(0)
let rect# = Pointer#(0)
let sh# = Pointer#(0)
let lbl# = Pointer#(0)

frm# = form#("Shadow Controls", 450, 320)

rect# = rectangle#(frm#)
rectangle_bounds#(rect#, 125, 40, 200, 100)
rectangle_fill#(rect#, "SteelBlue")

sh# = shadow#(rect#)
shadow_distance#(sh#, 5)
shadow_softness#(sh#, 0.3)

lbl# = label#(frm#, "Distance: 5", 175, 160)

let btn1# = button#(frm#, "Near")
button_bounds#(btn1#, 60, 200, 100, 30)
button_onclick#(btn1#, "SetNear")

let btn2# = button#(frm#, "Medium")
button_bounds#(btn2#, 170, 200, 100, 30)
button_onclick#(btn2#, "SetMedium")

let btn3# = button#(frm#, "Far")
button_bounds#(btn3#, 280, 200, 100, 30)
button_onclick#(btn3#, "SetFar")

form_show(frm#)

function SetNear(sender#)
  shadow_distance#(sh#, 3)
  shadow_softness#(sh#, 0.2)
  label_text#(lbl#, "Distance: 3")
endfunction

function SetMedium(sender#)
  shadow_distance#(sh#, 8)
  shadow_softness#(sh#, 0.4)
  label_text#(lbl#, "Distance: 8")
endfunction

function SetFar(sender#)
  shadow_distance#(sh#, 15)
  shadow_softness#(sh#, 0.6)
  label_text#(lbl#, "Distance: 15")
endfunction

Example 3: Shadow Directions

╯ shadow-directions.bas─◻✕
let frm# = Pointer#(0)
let rect1# = Pointer#(0)
let rect2# = Pointer#(0)
let sh1# = Pointer#(0)
let sh2# = Pointer#(0)

frm# = form#("Shadow Directions", 450, 250)

' Top-right light (raised look)
rect1# = rectangle#(frm#)
rectangle_bounds#(rect1#, 50, 70, 150, 100)
rectangle_fill#(rect1#, "White")
sh1# = shadow#(rect1#)
shadow_distance#(sh1#, 8)
shadow_direction#(sh1#, 45)
shadow_softness#(sh1#, 0.4)
let lbl1# = label#(frm#, "45 deg (SE)", 80, 180)

' Bottom-left light
rect2# = rectangle#(frm#)
rectangle_bounds#(rect2#, 250, 70, 150, 100)
rectangle_fill#(rect2#, "White")
sh2# = shadow#(rect2#)
shadow_distance#(sh2#, 8)
shadow_direction#(sh2#, 225)
shadow_softness#(sh2#, 0.4)
let lbl2# = label#(frm#, "225 deg (NW)", 275, 180)

form_show(frm#)

Best Practices

Practice	Why
Use consistent direction across UI	A single light source direction looks natural
Increase softness with distance	Farther shadows are softer in real life
Keep opacity moderate (0.3–0.6)	Overly dark shadows look harsh
Match shadow to elevation level	Cards: 3–5px, Buttons: 2–4px, Modals: 10–20px
Use GlowEffect for interactive controls	Shadow effects may block mouse events on the parent

⚠ Mouse Events: Shadow effects may block mouse events on the parent control. For interactive controls (buttons, etc.), consider using GlowEffectLib instead, or apply the shadow to a non-interactive backing shape.

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`shadow#(parent#)`	`shadow#@#`	Create effect
`shadow_free(effect#)`	`shadow_free@#`	Destroy effect
DISTANCE
`shadow_distance#(effect#, value)`	`shadow_distance#@#n`	Set offset (0–50 px)
`shadow_distance(effect#)`	`shadow_distance@#`	Get distance
DIRECTION
`shadow_direction#(effect#, degrees)`	`shadow_direction#@#n`	Set light angle (0–360)
`shadow_direction(effect#)`	`shadow_direction@#`	Get direction
SOFTNESS
`shadow_softness#(effect#, value)`	`shadow_softness#@#n`	Set blur (0–1)
`shadow_softness(effect#)`	`shadow_softness@#`	Get softness
OPACITY
`shadow_opacity#(effect#, value)`	`shadow_opacity#@#n`	Set opacity (0–1)
`shadow_opacity(effect#)`	`shadow_opacity@#`	Get opacity
COLOR
`shadow_color#(effect#, color$)`	`shadow_color#@#$`	Set color
`shadow_color(effect#)`	`shadow_color@#`	Get color
EFFECT CONTROL
`shadow_enabled#(effect#, value)`	`shadow_enabled#@#n`	Enable/disable
`shadow_enabled(effect#)`	`shadow_enabled@#`	Get enabled state
`shadow_trigger#(effect#, trigger$)`	`shadow_trigger#@#$`	Set trigger
`shadow_trigger$(effect#)`	`shadow_trigger$@#`	Get trigger
ERROR HANDLING
`shadow_error()`	`shadow_error@`	Last error code
`shadow_errormsg$()`	`shadow_errormsg$@`	Last error message
`shadow_strerror$(code)`	`shadow_strerror$@n`	Code to text
`shadow_clearerror()`	`shadow_clearerror@`	Clear error state

Library	Description
`GlowEffectLib`	Outer glow effects
`InnerGlowEffectLib`	Inner glow effects
`BevelEffectLib`	3D bevel effects
`ReflectionEffectLib`	Mirror reflection effects