MonochromeEffectLib — Plan9Basic Documentation

Overview

MonochromeEffectLib converts visual controls to grayscale/monochrome appearance, wrapping the FireMonkey TMonochromeEffect component. This is a simple but powerful effect for creating artistic photo filters, visual state indicators (active/inactive), or gallery hover effects. The effect is binary — on or off — with no gradual properties to adjust.

Property	Details
Library	`MonochromeEffectLib`
Prefix	`monochrome_`
Wraps	`TMonochromeEffect`
Functions	10
Type	Visual effect (binary on/off)

Category	Count	Description
Creation / Destruction	2	Create and free effect
Effect Control	4	Enabled and trigger get/set
Error Handling	4	Error codes and messages

🎨 Simple & Effective: Monochrome has no adjustable parameters — just create it and it works. Use the Enabled property to toggle between color and grayscale, or the Trigger property for automatic activation on hover/focus.

Control Compatibility

TMonochromeEffect is a texture-based filter that operates on bitmaps and rendered content. It works on controls that render with textures but does NOT work on styled controls.

Control	Works?	Notes
TImage	✅ Yes	Best results with loaded images
TRectangle	✅ Yes	Converts fill color to gray
TCircle	✅ Yes	Converts fill color to gray
TEllipse	✅ Yes	Converts fill color to gray
TRoundRect	✅ Yes	Converts fill color to gray
TPath	✅ Yes	Converts fill color to gray
TPanel	⚪ Partial	May affect background only
TButton	❌ No	Styled control — not affected
TCheckBox	❌ No	Styled control — not affected
TEdit	❌ No	Styled control — not affected
TLabel	❌ No	Styled control — not affected

⚠ Styled Controls: Buttons, checkboxes, edits, and labels use platform styling and are not affected by pixel-based effects. For grayscale UI elements, use shape controls (TRectangle, TCircle) instead.

Cross-Platform Support

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

Creation & Destruction

monochrome#(parent#)

Creates a new monochrome effect attached to the specified visual control. The effect is enabled by default.

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

monochrome_free(effect#)

Destroys the effect and releases associated resources.

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

╯ create-monochrome.bas─◻✕
' Apply monochrome — instantly grayscale
let mono# = monochrome#(img#)

' Start disabled (color), enable later
monochrome_enabled#(mono#, 0)

' Clean up when done
monochrome_free(mono#)

Error Handling

Function	Signature	Description
`monochrome_error()`	`monochrome_error@`	Returns last error code (0 = none)
`monochrome_errormsg$()`	`monochrome_errormsg$@`	Returns last error message
`monochrome_strerror$(code)`	`monochrome_strerror$@n`	Converts error code to text
`monochrome_clearerror()`	`monochrome_clearerror@`	Clears the error state

Code	Meaning
`0`	No error
`1`	Effect pointer is nil
`2`	Not a valid monochrome effect
`3`	Invalid property value
`4`	Parent pointer is nil
`5`	Invalid parent object

Effect Control

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

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

Complete Examples

Example 1: Grayscale Image

╯ grayscale-photo.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let mono# = Pointer#(0)

frm# = form#("Grayscale Photo", 400, 350)

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

' Apply monochrome effect
mono# = monochrome#(img#)

let lbl# = label#(frm#, "Photo converted to grayscale", 100, 270)

form_show(frm#)

Example 2: Toggle Color/Grayscale

╯ toggle-monochrome.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let mono# = Pointer#(0)
let statusLbl# = Pointer#(0)

frm# = form#("Toggle Demo", 400, 350)

img# = image#(frm#)
image_bounds#(img#, 50, 50, 300, 180)
image_load#(img#, "https://picsum.photos/300/180")

mono# = monochrome#(img#)
monochrome_enabled#(mono#, 0)  ' Start with color

let toggleBtn# = button#(frm#, "Toggle Grayscale")
button_bounds#(toggleBtn#, 125, 250, 150, 40)
button_onclick#(toggleBtn#, "ToggleMono")

statusLbl# = label#(frm#, "Currently: Color", 150, 300)

form_show(frm#)

function ToggleMono(sender#) local enabled
  enabled = monochrome_enabled(mono#)
  if enabled = 1 then
    monochrome_enabled#(mono#, 0)
    label_text#(statusLbl#, "Currently: Color")
  else
    monochrome_enabled#(mono#, 1)
    label_text#(statusLbl#, "Currently: Grayscale")
  endif
endfunction

Example 3: Card Selection Effect

╯ card-selection.bas─◻✕
let frm# = Pointer#(0)
let card1# = Pointer#(0)
let card2# = Pointer#(0)
let card3# = Pointer#(0)
let mono1# = Pointer#(0)
let mono2# = Pointer#(0)
let mono3# = Pointer#(0)

frm# = form#("Card Selection", 500, 300)

' Create colored cards
card1# = rectangle#(frm#)
rectangle_bounds#(card1#, 30, 50, 130, 150)
rectangle_fill#(card1#, "Blue")
rectangle_corners#(card1#, 8, 8)
mono1# = monochrome#(card1#)

card2# = rectangle#(frm#)
rectangle_bounds#(card2#, 180, 50, 130, 150)
rectangle_fill#(card2#, "Red")
rectangle_corners#(card2#, 8, 8)
mono2# = monochrome#(card2#)

card3# = rectangle#(frm#)
rectangle_bounds#(card3#, 330, 50, 130, 150)
rectangle_fill#(card3#, "Green")
rectangle_corners#(card3#, 8, 8)
mono3# = monochrome#(card3#)

' Selection buttons
let btn1# = button#(frm#, "Select 1")
button_bounds#(btn1#, 45, 220, 100, 30)
button_onclick#(btn1#, "Select1")

let btn2# = button#(frm#, "Select 2")
button_bounds#(btn2#, 195, 220, 100, 30)
button_onclick#(btn2#, "Select2")

let btn3# = button#(frm#, "Select 3")
button_bounds#(btn3#, 345, 220, 100, 30)
button_onclick#(btn3#, "Select3")

form_show(frm#)

function Select1(sender#)
  monochrome_enabled#(mono1#, 0)
  monochrome_enabled#(mono2#, 1)
  monochrome_enabled#(mono3#, 1)
endfunction

function Select2(sender#)
  monochrome_enabled#(mono1#, 1)
  monochrome_enabled#(mono2#, 0)
  monochrome_enabled#(mono3#, 1)
endfunction

function Select3(sender#)
  monochrome_enabled#(mono1#, 1)
  monochrome_enabled#(mono2#, 1)
  monochrome_enabled#(mono3#, 0)
endfunction

Trigger Strings

Triggers allow automatic activation/deactivation based on control state, without writing callback functions.

Trigger	Description
`IsMouseOver=true`	Activates when mouse hovers over control
`IsMouseOver=false`	Activates when mouse is NOT hovering
`IsFocused=true`	Activates when control has focus
`IsFocused=false`	Activates when control lacks focus

💡 Gallery Trick: Use monochrome_trigger#(mono#, "IsMouseOver=false") to create a photo gallery where images are grayscale by default and show color only on hover — a popular UI pattern.

╯ hover-gallery.bas─◻✕
' Color-on-hover gallery
let mono# = monochrome#(img#)
monochrome_trigger#(mono#, "IsMouseOver=false")

Best Practices

Practice	Why
Use TImage for photo grayscale effects	Best visual results with loaded images
Use shape controls for UI element effects	TRectangle, TCircle work well; styled controls do not
Avoid applying to styled controls	TButton, TEdit, TLabel are not affected by pixel filters
Use inverse triggers for hover galleries	`IsMouseOver=false` creates natural "color on hover" pattern
Combine with shadow or glow	Multiple effects on one control create richer visual feedback
GPU-accelerated, safe on many controls	Lightweight effect — no performance concerns with multiple instances

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`monochrome#(parent#)`	`monochrome#@#`	Create effect
`monochrome_free(effect#)`	`monochrome_free@#`	Destroy effect
EFFECT CONTROL
`monochrome_enabled#(effect#, value)`	`monochrome_enabled#@#n`	Enable/disable
`monochrome_enabled(effect#)`	`monochrome_enabled@#`	Get enabled state
`monochrome_trigger#(effect#, trigger$)`	`monochrome_trigger#@#$`	Set trigger
`monochrome_trigger$(effect#)`	`monochrome_trigger$@#`	Get trigger
ERROR HANDLING
`monochrome_error()`	`monochrome_error@`	Last error code
`monochrome_errormsg$()`	`monochrome_errormsg$@`	Last error message
`monochrome_strerror$(code)`	`monochrome_strerror$@n`	Code to text
`monochrome_clearerror()`	`monochrome_clearerror@`	Clear error state

Library	Description
`InvertEffectLib`	Color inversion effect
`SepiaEffectLib`	Vintage sepia tone effect
`ContrastEffectLib`	Contrast/brightness adjustment
`HueAdjustEffectLib`	Color hue shifting
`ShadowEffectLib`	Drop shadow effect