README
¶
vreactive - Reactive Layer for vgui & vtui
vreactive provides a lightweight, thread-safe, and cycle-protected reactive primitives library for Go UI frameworks (vtui and vgui).
Features
Property[T]: Reactive state container with subscription handlers.Computed[T]/Computed2[T]/ComputedIf[T]: Automatically recomputed properties derived from reactive dependencies, including declarative ternary expressions (ComputedIf).Bind[T]: One-way property synchronization.StateMachine: Declarative state transitions and property setters.Behavior[T]&Animator[T]: Smooth and discrete property transition animations (SmoothBehavior,DiscreteBehavior) supporting easing curves (EaseOutBack,EaseInOutQuad,EaseOutBounce, etc.).RGBInterpolator: Seamless 24-bit TrueColor animation and channel blending.Effect(fn, deps...): Signal-based side-effects running initially and tracking multi-property changes.TwoWayBind: Cycle-safe bidirectional binding between state properties and external UI components.BindEnabled/BindVisible: One-line declarative adapters linking widget flags directly to boolean properties.- Cycle Detection: Prevents infinite notification loops by enforcing a maximum call depth limit.
- Thread Safety: Mutex-protected reads/writes and
SafeSetfor asynchronous background goroutine updates via UI event queues.
Usage Example
nameProp := vreactive.NewProperty("Alice")
greetingProp := vreactive.Computed(nameProp, func(name string) string {
return "Hello, " + name + "!"
})
// Reacting to changes
greetingProp.OnChange(func(val string) {
fmt.Println(val)
})
nameProp.Set("Bob") // Prints "Hello, Bob!"
Documentation
¶
Index ¶
- func Bind[T any](dest Property[T], src Property[T])
- func BindEnabled(prop Property[bool], target Disabler) func()
- func BindTo[T any](prop Property[T], target func(T)) func()
- func BindVisible(prop Property[bool], target VisibilitySetter) func()
- func EaseInBack(t float64) float64
- func EaseInCubic(t float64) float64
- func EaseInOutCubic(t float64) float64
- func EaseInOutQuad(t float64) float64
- func EaseInQuad(t float64) float64
- func EaseOutBack(t float64) float64
- func EaseOutBounce(t float64) float64
- func EaseOutCubic(t float64) float64
- func EaseOutQuad(t float64) float64
- func Effect(fn func(), deps ...Watcher) func()
- func Float64Interpolator(start, end float64, progress float64) float64
- func IntInterpolator(start, end int, progress float64) int
- func Linear(t float64) float64
- func RGBInterpolator(start, end uint32, progress float64) uint32
- func SafeSet[T any](p Property[T], val T)
- func SetProp[T any](p Property[T], val T) func()
- func TwoWayBind[T comparable](prop Property[T], get func() T, set func(T), ...) func()
- type AnimationManager
- type Animator
- type BehaviorDef
- type Disabler
- type DiscreteAnimator
- type DiscreteBehavior
- type EasingFunc
- type Interpolator
- type Property
- func Computed[T any, A any](dep Property[A], compute func(A) T) Property[T]
- func Computed2[T any, A, B any](dep1 Property[A], dep2 Property[B], compute func(A, B) T) Property[T]
- func ComputedIf[T any](cond Property[bool], whenTrue, whenFalse T) Property[T]
- func NewProperty[T any](initial T) Property[T]
- type SmoothAnimator
- type SmoothBehavior
- type StateMachine
- type UpdateQueue
- type VisibilitySetter
- type Watcher
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BindEnabled ¶
BindEnabled binds a widget's enabled state to prop (enabled when true).
func BindVisible ¶
func BindVisible(prop Property[bool], target VisibilitySetter) func()
BindVisible binds a widget's visibility to prop.
func EaseInBack ¶
func EaseInOutCubic ¶
func EaseInOutQuad ¶
func EaseOutBack ¶
Back easings (overshooting transitions, corresponding to QML Easing.OutBack / InBack)
func EaseOutCubic ¶
func EaseOutQuad ¶
func Effect ¶
func Effect(fn func(), deps ...Watcher) func()
Effect runs fn immediately and re-executes it whenever any dependency changes. It represents the standard Signal Effect pattern (SolidJS / Svelte / Vue).
func Float64Interpolator ¶
func IntInterpolator ¶
func RGBInterpolator ¶
RGBInterpolator smoothly blends between two 24-bit 0xRRGGBB colors across RGB channels.
func SafeSet ¶
SafeSet updates the property value on the global update queue if configured. Extremely useful for thread-safe mutation from background goroutines.
func TwoWayBind ¶
func TwoWayBind[T comparable]( prop Property[T], get func() T, set func(T), listen func(onChange func(T)) (unlisten func()), ) func()
TwoWayBind creates a seamless 2-way binding between a Property[T] and an external control, eliminating infinite ping-pong notification echoes.
Types ¶
type AnimationManager ¶
AnimationManager handles the ticking of animators.
var GlobalAnimationManager AnimationManager
GlobalAnimationManager should be set by the UI framework.
type BehaviorDef ¶
type DiscreteAnimator ¶
type DiscreteAnimator[T any] struct { Target T }
func (*DiscreteAnimator[T]) Tick ¶
func (a *DiscreteAnimator[T]) Tick(dt float64) (T, bool)
type DiscreteBehavior ¶
type DiscreteBehavior[T any] struct{}
func (*DiscreteBehavior[T]) CreateAnimator ¶
func (b *DiscreteBehavior[T]) CreateAnimator(start, end T) Animator[T]
type EasingFunc ¶
EasingFunc maps a normalized linear progress [0..1] to an eased progress value.
type Interpolator ¶
type Property ¶
type Property[T any] interface { Get() T Set(val T) OnChange(handler func(newVal T)) func() SetBehavior(b BehaviorDef[T]) Watch(handler func()) func() }
func Computed2 ¶
func Computed2[T any, A, B any](dep1 Property[A], dep2 Property[B], compute func(A, B) T) Property[T]
Computed2 creates a property depending on two reactive sources.
func ComputedIf ¶
ComputedIf creates a reactive property that evaluates to whenTrue when cond is true, or whenFalse otherwise.
func NewProperty ¶
type SmoothAnimator ¶
type SmoothAnimator[T any] struct { Start T End T Duration float64 Elapsed float64 Easing EasingFunc Interp Interpolator[T] }
func (*SmoothAnimator[T]) Tick ¶
func (a *SmoothAnimator[T]) Tick(dt float64) (T, bool)
type SmoothBehavior ¶
type SmoothBehavior[T any] struct { Duration float64 Easing EasingFunc Interp Interpolator[T] }
SmoothBehavior smoothly interpolates property transitions over Duration with optional Easing.
func (*SmoothBehavior[T]) CreateAnimator ¶
func (b *SmoothBehavior[T]) CreateAnimator(start, end T) Animator[T]
type StateMachine ¶
StateMachine helps defining declarative UI states.
func NewStateMachine ¶
func NewStateMachine(initialState string) *StateMachine
func (*StateMachine) AddState ¶
func (sm *StateMachine) AddState(name string, setters ...func())
type UpdateQueue ¶
type UpdateQueue interface {
PostTask(task func())
}
UpdateQueue interface allows posting tasks to the UI thread.
var GlobalUpdateQueue UpdateQueue
GlobalUpdateQueue should be set to the UI framework's task queue (e.g. vtui.FrameManager).
type VisibilitySetter ¶
type VisibilitySetter interface {
SetVisible(bool)
}
Source Files