ColorAnimationLib — Plan9Basic Documentation

ColorAnimationLib — Color Animation Library

Smoothly animates color properties of visual controls — fill colors, stroke colors, and text colors. Essential for hover effects, state transitions, visual feedback, and decorative color cycling. Includes 4 color utility functions for converting between named colors, hex strings, and numeric ARGB values. 50 functions.

Category	Count	Description
Error Handling	4	colorani_error, errormsg$, strerror$, clearerror
Color Utilities	4	colortoalphacolor, alphacolortostring$, rgb, rgba
Creation & Destruction	3	colorani# (2 overloads), colorani_free
Playback Control	3	start, stop, stopatcurrent
Core Properties	10	propertyname, startvalue, stopvalue, duration, delay (get/set)
Behavior — Easing	4	animationtype, interpolation (get/set)
Behavior — Flags	10	autoreverse, inverse, loop, enabled, startfromcurrent (get/set)
State Queries	3	running, normalizedtime, name$
Triggers	4	trigger, triggerinverse (get/set)
Events	5	onfinish, onprocess (get/set), clearcallbacks#

Cross-Platform Support

Platform	Status	Notes
Windows	✅ Full Support	Win32/Win64
Linux	✅ Full Support	GTK-based
Android	✅ Full Support	Hardware-accelerated

Error Handling

Function	Signature	Description
`colorani_error()`	`colorani_error@`	Last error code (0 = no error)
`colorani_errormsg$()`	`colorani_errormsg$@`	Last error message as string
`colorani_strerror$(code)`	`colorani_strerror$@n`	Description for a given error code
`colorani_clearerror()`	`colorani_clearerror@`	Clear the error state

Error Codes

Code	Constant	Description
0	ERR_NONE	No error
1	ERR_NIL_ANIMATION	Animation pointer is nil
2	ERR_INVALID_PROPERTY	Invalid property name or object
3	ERR_INVALID_VALUE	Invalid color value
4	ERR_ANIMATION_RUNNING	Cannot modify while animation is running

How It Works

A color animation smoothly interpolates between two colors over time. It targets a color property on its parent control (such as Fill.Color or Stroke.Color) and transitions from a start color to a stop color. Color values are specified as numeric integers (ARGB format), using the provided utility functions to convert from named colors or RGB components:

╯ basic pattern─◻✕
' 1. Create the animation on a shape
let ani# = colorani#(myRect#)

' 2. Set which color property to animate
colorani_propertyname#(ani#, "Fill.Color")

' 3. Set start and stop colors (as numeric values)
colorani_startvalue#(ani#, colortoalphacolor("Blue"))
colorani_stopvalue#(ani#, colortoalphacolor("Red"))

' 4. Set timing
colorani_duration#(ani#, 2.0)

' 5. Start!
colorani_start(ani#)

⚠ Important — String vs Numeric colors: Shape functions like rectangle_fill# take string color names ("Red", "#FF0000"). Animation functions colorani_startvalue# and colorani_stopvalue# take numeric color values. Use colortoalphacolor() or rgb() to convert.

Color Values

Color animation works with numeric ARGB values (32-bit integers where Alpha, Red, Green, Blue each occupy 8 bits). You can specify colors three ways:

Named Colors

Pass a color name to colortoalphacolor():

Color Name	Sample	Color Name	Sample
Black		White
Red		Green
Blue		Yellow
Cyan		Magenta
Orange		Purple
Pink		Lime
Navy		Maroon
Teal		Olive
Gray / Grey		Silver
Aqua		Fuchsia

Hex Strings

Also supported by colortoalphacolor():

╯ hex formats─◻✕
' 6-digit hex (opaque)
let coral = colortoalphacolor("#FF7F50")

' 8-digit hex with alpha (AARRGGBB)
let semiBlue = colortoalphacolor("#800000FF")

RGB / RGBA Components

╯ component colors─◻✕
' Opaque coral (R=255, G=127, B=80)
let coral = rgb(255, 127, 80)

' Semi-transparent blue (A=128)
let ghostBlue = rgba(0, 0, 255, 128)

Color Utility Functions

Function	Signature	Description
`colortoalphacolor(name$)`	`colortoalphacolor@$`	Convert color name or hex string to numeric ARGB value
`alphacolortostring$(color)`	`alphacolortostring$@n`	Convert numeric ARGB to hex string
`rgb(r, g, b)`	`rgb@nnn`	Create opaque color from R, G, B components (0–255)
`rgba(r, g, b, a)`	`rgba@nnnn`	Create color with alpha from R, G, B, A components (0–255)

ⓘ Note: These are general-purpose color utilities registered by ColorAnimationLib but usable anywhere in your program. Use colortoalphacolor for named colors and hex strings; use rgb/rgba for computed or custom colors.

Animatable Color Properties

Property Name	Applies To	Description
`Fill.Color`	Shapes (rectangle, circle, ellipse, pie, arc, path)	Background fill color
`Stroke.Color`	Shapes	Border/outline color
`TextSettings.FontColor`	Labels, Edit, Memo	Text color

Interpolation & Easing

Color interpolation blends the R, G, B, and A channels independently using the selected curve. The same 11 interpolation types and 3 easing modes available in FloatAnimationLib apply here:

Interpolation Curves

Interpolation	Character	Best For
`"Linear"`	Constant speed	Smooth, even color transitions
`"Quadratic"`	Gentle curve	Subtle hover effects
`"Cubic"`	Moderate curve	UI state changes
`"Quartic"`	Pronounced curve	Dramatic color shifts
`"Quintic"`	Very pronounced	Emphatic feedback
`"Sinusoidal"`	Sine-wave smooth	Pulsing glow effects
`"Exponential"`	Sharp curve	Flash-then-settle effects
`"Circular"`	Arc-based	Organic color blending
`"Elastic"`	Springy overshoot	Bouncy color flicker
`"Back"`	Overshoots then settles	Color “snap” effects
`"Bounce"`	Bouncing ball	Playful color pulsing

Easing Types (AnimationType)

Type	Effect	Description
`"In"`	Slow start → fast end	Color change accelerates
`"Out"`	Fast start → slow end	Color change decelerates
`"InOut"`	Slow → fast → slow	Smooth start and end

Creation & Destruction

Function	Signature	Description
`colorani#(parent#)`	`colorani#@#`	Create animation attached to parent control
`colorani#(parent#, name$)`	`colorani#@#$`	Create named animation attached to parent
`colorani_free(ani#)`	`colorani_free@#`	Destroy animation object

Playback Control

Function	Signature	Description
`colorani_start(ani#)`	`colorani_start@#`	Start the animation
`colorani_stop(ani#)`	`colorani_stop@#`	Stop and reset to start color
`colorani_stopatcurrent(ani#)`	`colorani_stopatcurrent@#`	Stop at current blended color

Core Properties

Property Name

Function	Signature	Description
`colorani_propertyname#(ani#, name$)`	`colorani_propertyname#@#$`	Set which color property to animate
`colorani_propertyname$(ani#)`	`colorani_propertyname$@#`	Get the property name

Color Range

Function	Signature	Description
`colorani_startvalue#(ani#, color)`	`colorani_startvalue#@#n`	Set start color (numeric ARGB)
`colorani_startvalue(ani#)`	`colorani_startvalue@#`	Get start color
`colorani_stopvalue#(ani#, color)`	`colorani_stopvalue#@#n`	Set end color (numeric ARGB)
`colorani_stopvalue(ani#)`	`colorani_stopvalue@#`	Get end color

Timing

Function	Signature	Description
`colorani_duration#(ani#, seconds)`	`colorani_duration#@#n`	Set duration in seconds
`colorani_duration(ani#)`	`colorani_duration@#`	Get duration
`colorani_delay#(ani#, seconds)`	`colorani_delay#@#n`	Set delay before animation starts
`colorani_delay(ani#)`	`colorani_delay@#`	Get delay

Behavior Flags

Easing & Interpolation

Function	Signature	Description
`colorani_animationtype#(ani#, type$)`	`colorani_animationtype#@#$`	Set easing: `"In"`, `"Out"`, `"InOut"`
`colorani_animationtype$(ani#)`	`colorani_animationtype$@#`	Get easing type
`colorani_interpolation#(ani#, type$)`	`colorani_interpolation#@#$`	Set interpolation curve
`colorani_interpolation$(ani#)`	`colorani_interpolation$@#`	Get interpolation type

Boolean Flags

Function	Signature	Description
`colorani_autoreverse#(ani#, flag)`	`colorani_autoreverse#@#n`	If 1, plays forward then backward
`colorani_autoreverse(ani#)`	`colorani_autoreverse@#`	Get autoreverse flag
`colorani_inverse#(ani#, flag)`	`colorani_inverse#@#n`	If 1, plays in reverse direction
`colorani_inverse(ani#)`	`colorani_inverse@#`	Get inverse flag
`colorani_loop#(ani#, flag)`	`colorani_loop#@#n`	If 1, loops indefinitely
`colorani_loop(ani#)`	`colorani_loop@#`	Get loop flag
`colorani_enabled#(ani#, flag)`	`colorani_enabled#@#n`	Enable or disable the animation
`colorani_enabled(ani#)`	`colorani_enabled@#`	Get enabled state
`colorani_startfromcurrent#(ani#, flag)`	`colorani_startfromcurrent#@#n`	If 1, begins from current color
`colorani_startfromcurrent(ani#)`	`colorani_startfromcurrent@#`	Get startfromcurrent flag

State Queries

Function	Signature	Description
`colorani_running(ani#)`	`colorani_running@#`	Returns 1 if currently animating
`colorani_normalizedtime(ani#)`	`colorani_normalizedtime@#`	Returns progress from 0.0 to 1.0
`colorani_name$(ani#)`	`colorani_name$@#`	Get the animation’s name

Triggers

Triggers let a color animation start or reverse automatically when a parent property changes:

Function	Signature	Description
`colorani_trigger#(ani#, expr$)`	`colorani_trigger#@#$`	Set trigger expression (starts animation)
`colorani_trigger$(ani#)`	`colorani_trigger$@#`	Get trigger expression
`colorani_triggerinverse#(ani#, expr$)`	`colorani_triggerinverse#@#$`	Set inverse trigger (reverses animation)
`colorani_triggerinverse$(ani#)`	`colorani_triggerinverse$@#`	Get inverse trigger expression

╯ trigger example─◻✕
' Auto-highlight on hover: normal color → highlight
colorani_trigger#(ani#, "IsMouseOver=true")
colorani_triggerinverse#(ani#, "IsMouseOver=false")

Events

Event Setter	Getter	Callback Signature	Description
`colorani_onfinish#(ani#, func$)`	`colorani_onfinish$(ani#)`	`function name(sender#)`	Fired when animation completes
`colorani_onprocess#(ani#, func$)`	`colorani_onprocess$(ani#)`	`function name(sender#)`	Fired on every animation frame
`colorani_clearcallbacks#(ani#)`	—	—	Disconnect all callbacks

Complete Examples

Fill Color Transition

╯ color-transition.bas─◻✕
let frm# = form#("Color Demo", 400, 300)
form_position#(frm#, 4)

let rect# = rectangle#(frm#, 100, 100, 200, 100)
rectangle_fill#(rect#, "Blue")

' Smoothly transition Blue → Red and back
let colorAni# = colorani#(rect#)
colorani_propertyname#(colorAni#, "Fill.Color")
colorani_startvalue#(colorAni#, colortoalphacolor("Blue"))
colorani_stopvalue#(colorAni#, colortoalphacolor("Red"))
colorani_duration#(colorAni#, 2.0)
colorani_autoreverse#(colorAni#, 1)
colorani_loop#(colorAni#, 1)
colorani_start(colorAni#)

form_show(frm#)

while form_visible(frm#) = 1
    processmessages()
end while

Custom RGB Colors

╯ rgb-colors.bas─◻✕
let frm# = form#("RGB Demo", 400, 300)
form_position#(frm#, 4)

let rect# = rectangle#(frm#, 100, 100, 200, 100)
rectangle_fill#(rect#, "#FF7F50")

' Coral (255,127,80) → Teal (0,128,128)
let coral = rgb(255, 127, 80)
let teal = rgb(0, 128, 128)

let colorAni# = colorani#(rect#)
colorani_propertyname#(colorAni#, "Fill.Color")
colorani_startvalue#(colorAni#, coral)
colorani_stopvalue#(colorAni#, teal)
colorani_duration#(colorAni#, 2.0)
colorani_autoreverse#(colorAni#, 1)
colorani_loop#(colorAni#, 1)
colorani_start(colorAni#)

form_show(frm#)

while form_visible(frm#) = 1
    processmessages()
end while

Text Color Animation

╯ text-color.bas─◻✕
let frm# = form#("Text Color Demo", 400, 200)
form_position#(frm#, 4)

let lbl# = label#(frm#, "Hello World!")
label_move#(lbl#, 100, 80)
label_fontsize#(lbl#, 24)

' Animate text color: Grey → Red and back
let colorAni# = colorani#(lbl#)
colorani_propertyname#(colorAni#, "TextSettings.FontColor")
colorani_startvalue#(colorAni#, colortoalphacolor("Grey"))
colorani_stopvalue#(colorAni#, colortoalphacolor("Red"))
colorani_duration#(colorAni#, 1.5)
colorani_autoreverse#(colorAni#, 1)
colorani_loop#(colorAni#, 1)
colorani_start(colorAni#)

form_show(frm#)

while form_visible(frm#) = 1
    processmessages()
end while

Stroke Color Animation

╯ border-color.bas─◻✕
let frm# = form#("Border Demo", 400, 300)
form_position#(frm#, 4)

let rect# = rectangle#(frm#, 100, 75, 200, 150)
rectangle_fill#(rect#, "White")
rectangle_stroke#(rect#, "Blue")
rectangle_strokethickness#(rect#, 4)

' Animate border: Blue → Orange
let colorAni# = colorani#(rect#)
colorani_propertyname#(colorAni#, "Stroke.Color")
colorani_startvalue#(colorAni#, colortoalphacolor("Blue"))
colorani_stopvalue#(colorAni#, colortoalphacolor("Orange"))
colorani_duration#(colorAni#, 1.0)
colorani_autoreverse#(colorAni#, 1)
colorani_loop#(colorAni#, 1)
colorani_start(colorAni#)

form_show(frm#)

while form_visible(frm#) = 1
    processmessages()
end while

Multi-Property Color Animation

╯ multi-color.bas─◻✕
let frm# = form#("Multi-Color Demo", 400, 300)
form_position#(frm#, 4)

let rect# = rectangle#(frm#, 100, 75, 200, 150)
rectangle_fill#(rect#, "Red")
rectangle_stroke#(rect#, "White")
rectangle_strokethickness#(rect#, 3)

' Animate fill: Red → Purple
let fillAni# = colorani#(rect#, "FillAni")
colorani_propertyname#(fillAni#, "Fill.Color")
colorani_startvalue#(fillAni#, colortoalphacolor("Red"))
colorani_stopvalue#(fillAni#, colortoalphacolor("Purple"))
colorani_duration#(fillAni#, 2.0)
colorani_autoreverse#(fillAni#, 1)
colorani_loop#(fillAni#, 1)

' Animate stroke: White → Yellow (different duration)
let strokeAni# = colorani#(rect#, "StrokeAni")
colorani_propertyname#(strokeAni#, "Stroke.Color")
colorani_startvalue#(strokeAni#, colortoalphacolor("White"))
colorani_stopvalue#(strokeAni#, colortoalphacolor("Yellow"))
colorani_duration#(strokeAni#, 1.5)
colorani_autoreverse#(strokeAni#, 1)
colorani_loop#(strokeAni#, 1)

' Start both animations
colorani_start(fillAni#)
colorani_start(strokeAni#)

form_show(frm#)

while form_visible(frm#) = 1
    processmessages()
end while

Best Practices

Practice	Why
Use `colortoalphacolor()` for named and hex colors	Converts strings to the numeric format the animation needs
Use `rgb()` / `rgba()` for computed custom colors	When R, G, B values come from variables or calculations
Use `"Linear"` for smooth even transitions	Other curves can create unexpected color jumps in the middle
Use `autoreverse + loop` for continuous cycling	Creates a smooth back-and-forth color oscillation
Use `startfromcurrent = 1` for interruptions	Avoids color jumps when restarting mid-transition
Animate `Fill.Color` for background transitions	Most common use case for shape color changes
Animate `Stroke.Color` for border highlights	Use with thicker strokes (3–4px) for visible effect
Animate `TextSettings.FontColor` for text emphasis	Works on labels and text input controls
Name animations when stacking multiple on one control	Use `colorani#(parent#, name$)` for clarity
Use `delay` for staggered color effects	Different delays create cascading color wave effects

Quick Reference

Function	Signature	Description
`colorani_error / errormsg$ / strerror$ / clearerror`	`various`	Error handling (4)
`colortoalphacolor / alphacolortostring$ / rgb / rgba`	`various`	Color utilities (4)
`colorani#(parent#[, name$])`	`colorani#@# / colorani#@#$`	Create (2 overloads)
`colorani_free(ani#)`	`colorani_free@#`	Destroy
`colorani_start / stop / stopatcurrent`	`various`	Playback control (3)
`colorani_propertyname# / propertyname$`	`various`	Target property (2)
`colorani_startvalue / stopvalue`	`various`	Color range (4)
`colorani_duration / delay`	`various`	Timing (4)
`colorani_animationtype / interpolation`	`various`	Easing & curves (4)
`colorani_autoreverse / inverse / loop / enabled / startfromcurrent`	`various`	Behavior flags (10)
`colorani_running / normalizedtime / name$`	`various`	State queries (3)
`colorani_trigger / triggerinverse`	`various`	Automatic triggers (4)
`colorani_onfinish / onprocess / clearcallbacks#`	`various`	Events (5)

50 functions (46 animation + 4 color utilities). Part of the Plan9Basic Animation library system.