FillEffectLib — Plan9Basic Documentation

FillEffectLib — Solid Color Fill

Fills a visual control with a solid colour overlay using a numeric ARGB value. Every pixel of the control is replaced by the specified colour. Wraps FireMonkey’s TFillEffect. Useful for colour masking, selection indicators, and toggling between the original appearance and a flat-colour state. 12 functions.

Category	Count	Description
Error Handling	4	fill_error, errormsg$, strerror$, clearerror
Creation & Destruction	2	fill# (create), fill_free (destroy)
Properties	2	color (get/set)
Effect Control	4	enabled, trigger (get/set)

ARGB Colour Values

Colours are specified as numeric ARGB values (Alpha-Red-Green-Blue packed into one number). Each channel ranges 0–255. The Delphi hex notation is $AARRGGBB.

Colour	Hex	Decimal
White	`$FFFFFFFF`	4294967295
Black	`$FF000000`	4278190080
Red	`$FFFF0000`	4294901760
Green	`$FF00FF00`	4278255360
Blue	`$FF0000FF`	4278190335
Yellow	`$FFFFFF00`	4294967040
Cyan	`$FF00FFFF`	4278255615
Magenta	`$FFFF00FF`	4294902015
50% Red	`$80FF0000`	2164195328

ⓘ Alpha channel: The first byte controls transparency. $FF = fully opaque, $80 = 50% transparent, $00 = invisible. Use lower alpha values for tinting rather than complete replacement.

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
`fill_error()`	`fill_error@`	Returns last error code (0 = no error)
`fill_errormsg$()`	`fill_errormsg$@`	Returns last error message as string
`fill_strerror$(code)`	`fill_strerror$@n`	Converts an error code to descriptive text
`fill_clearerror()`	`fill_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 TFillEffect
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
`fill#(parent#)`	`fill#@#`	Creates a fill effect on the given control. Returns the effect pointer.
`fill_free(effect#)`	`fill_free@#`	Destroys the effect and removes it from the parent.

Color

Sets the fill colour as a numeric ARGB value (not a colour name string). Default is white (4294967295).

Function	Signature	Description
`fill_color#(effect#, color)`	`fill_color#@#n`	Sets fill colour (ARGB number)
`fill_color(effect#)`	`fill_color@#`	Gets current fill colour

Effect Control

Enabled

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

Trigger

Function	Signature	Description
`fill_trigger#(effect#, trigger$)`	`fill_trigger#@#$`	Sets trigger string
`fill_trigger$(effect#)`	`fill_trigger$@#`	Gets current trigger string

Complete Examples

Basic Red Fill

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

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

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

fl# = fill#(rect#)
fill_color#(fl#, 4294901760)  ' Red ($FFFF0000)

form_show(frm#)

Colour Toggle with Buttons

╯ fill-toggle.bas─◻✕
let frm# = Pointer#(0)
let rect# = Pointer#(0)
let fl# = Pointer#(0)
let lbl# = Pointer#(0)

frm# = form#("Fill Colors", 450, 320)

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

fl# = fill#(rect#)
fill_enabled#(fl#, 0)

lbl# = label#(frm#, "Fill: Off", 180, 160)

let btn1# = button#(frm#, "Off")
button_bounds#(btn1#, 40, 200, 80, 30)
button_onclick#(btn1#, "SetOff")

let btn2# = button#(frm#, "Red")
button_bounds#(btn2#, 130, 200, 80, 30)
button_onclick#(btn2#, "SetRed")

let btn3# = button#(frm#, "Green")
button_bounds#(btn3#, 220, 200, 80, 30)
button_onclick#(btn3#, "SetGreen")

let btn4# = button#(frm#, "Blue")
button_bounds#(btn4#, 310, 200, 80, 30)
button_onclick#(btn4#, "SetBlue")

form_show(frm#)

function SetOff(sender#)
  fill_enabled#(fl#, 0)
  label_text#(lbl#, "Fill: Off")
endfunction

function SetRed(sender#)
  fill_color#(fl#, 4294901760)
  fill_enabled#(fl#, 1)
  label_text#(lbl#, "Fill: Red")
endfunction

function SetGreen(sender#)
  fill_color#(fl#, 4278255360)
  fill_enabled#(fl#, 1)
  label_text#(lbl#, "Fill: Green")
endfunction

function SetBlue(sender#)
  fill_color#(fl#, 4278190335)
  fill_enabled#(fl#, 1)
  label_text#(lbl#, "Fill: Blue")
endfunction

Fill Gallery — Side by Side

╯ fill-gallery.bas─◻✕
let frm# = Pointer#(0)

frm# = form#("Fill Gallery", 500, 280)

' Red fill
let rect1# = rectangle#(frm#)
rectangle_bounds#(rect1#, 40, 60, 120, 100)
rectangle_fill#(rect1#, "Gray")
let fl1# = fill#(rect1#)
fill_color#(fl1#, 4294901760)
let lbl1# = label#(frm#, "Red Fill", 70, 170)

' Green fill
let rect2# = rectangle#(frm#)
rectangle_bounds#(rect2#, 190, 60, 120, 100)
rectangle_fill#(rect2#, "Gray")
let fl2# = fill#(rect2#)
fill_color#(fl2#, 4278255360)
let lbl2# = label#(frm#, "Green Fill", 215, 170)

' Blue fill
let rect3# = rectangle#(frm#)
rectangle_bounds#(rect3#, 340, 60, 120, 100)
rectangle_fill#(rect3#, "Gray")
let fl3# = fill#(rect3#)
fill_color#(fl3#, 4278190335)
let lbl3# = label#(frm#, "Blue Fill", 365, 170)

form_show(frm#)

Best Practices

Practice	Why
Use `fill_enabled#` to toggle, not color 0	Disabling is cleaner than setting a transparent color
Use semi-transparent alpha for tinting	`$80FF0000` tints red instead of replacing completely
Colour is numeric ARGB, not a string	Use `FillRGBEffectLib` if you need the same API
Use trigger for hover feedback	`fill_trigger#(fl#, "IsMouseOver=true")`
Use for selection indicators	Toggle fill on/off to show selected state

Quick Reference

Function	Signature	Description
ERROR HANDLING
`fill_error()`	`fill_error@`	Last error code
`fill_errormsg$()`	`fill_errormsg$@`	Last error message
`fill_strerror$(code)`	`fill_strerror$@n`	Error code to text
`fill_clearerror()`	`fill_clearerror@`	Clear error state
CREATION & DESTRUCTION
`fill#(parent#)`	`fill#@#`	Create effect on control
`fill_free(effect#)`	`fill_free@#`	Destroy effect
PROPERTIES
`fill_color#(effect#, color)`	`fill_color#@#n`	Set colour (ARGB number)
`fill_color(effect#)`	`fill_color@#`	Get colour
EFFECT CONTROL
`fill_enabled#(effect#, val)`	`fill_enabled#@#n`	Enable (1) / disable (0)
`fill_enabled(effect#)`	`fill_enabled@#`	Get enabled state
`fill_trigger#(effect#, str$)`	`fill_trigger#@#$`	Set trigger string
`fill_trigger$(effect#)`	`fill_trigger$@#`	Get trigger string

12 functions. Part of the Plan9Basic visual effects library system.