Documentation
¶
Overview ¶
Package transition provides animated wrapper widgets that apply motion effects to child widgets.
There are two levels of API: high-level convenience widgets (Slide, Fade) and the lower-level Transition wrapper with composable Effect values.
High-Level Widgets ¶
Slide and Fade are standalone widgets that wrap a child and animate a single property. They implement widget.Lifecycle for auto-start on mount and follow the same time-based animation pattern as the progress spinner (elapsed time from widget.Context.Now, easing functions).
slide := transition.NewSlide(myWidget,
transition.SlideFrom(transition.FromTop),
transition.SlideDuration(300 * time.Millisecond),
transition.SlideEasing(animation.EaseOutCubic),
)
fade := transition.NewFade(myWidget,
transition.FadeDuration(200 * time.Millisecond),
transition.FadeEasing(animation.EaseInOutCubic),
)
Low-Level Transition Wrapper ¶
Transition created via Wrap supports composable effects (fade, slide, scale) for enter/exit animations. Use this when you need combined effects or explicit Show/Hide lifecycle control.
wrapped := transition.Wrap(myWidget,
transition.EnterEffect(transition.FadeIn()),
transition.ExitEffect(transition.SlideOut(transition.ToBottom)),
transition.Duration(300 * time.Millisecond),
)
wrapped.Show() // plays enter animation
wrapped.Hide() // plays exit animation, then hides widget
Canvas Requirements ¶
Fade effects work best when the canvas implements OpacityPusher for true per-pixel opacity. Without it, Fade falls back to a background- color overlay approach (drawing a semi-transparent rect over the child). Slide effects use widget.Canvas.PushTransform.
Retained Mode ¶
During animation, transition widgets call widget.WidgetBase.SetNeedsRedraw and widget.Context.InvalidateRect to request continuous repainting until the animation completes.
Index ¶
- type Direction
- type Effect
- type Fade
- func (f *Fade) Child() widget.Widget
- func (f *Fade) Children() []widget.Widget
- func (f *Fade) Draw(ctx widget.Context, canvas widget.Canvas)
- func (f *Fade) Event(ctx widget.Context, e event.Event) bool
- func (f *Fade) FadeIn()
- func (f *Fade) FadeOut()
- func (f *Fade) IsAnimating() bool
- func (f *Fade) Layout(ctx widget.Context, constraints geometry.Constraints) geometry.Size
- func (f *Fade) Mount(_ widget.Context)
- func (f *Fade) Opacity() float32
- func (f *Fade) SetOpacity(opacity float32)
- func (f *Fade) Unmount()
- type FadeOption
- type OpacityPusher
- type Option
- type Slide
- func (s *Slide) Child() widget.Widget
- func (s *Slide) Children() []widget.Widget
- func (s *Slide) Draw(ctx widget.Context, canvas widget.Canvas)
- func (s *Slide) Event(ctx widget.Context, e event.Event) bool
- func (s *Slide) IsAnimating() bool
- func (s *Slide) Layout(ctx widget.Context, constraints geometry.Constraints) geometry.Size
- func (s *Slide) Mount(_ widget.Context)
- func (s *Slide) Progress() float32
- func (s *Slide) SetChild(child widget.Widget)
- func (s *Slide) SlideIn()
- func (s *Slide) SlideOut()
- func (s *Slide) Unmount()
- type SlideOption
- type Transition
- func (t *Transition) Child() widget.Widget
- func (t *Transition) Children() []widget.Widget
- func (t *Transition) Draw(ctx widget.Context, canvas widget.Canvas)
- func (t *Transition) Event(ctx widget.Context, e event.Event) bool
- func (t *Transition) Hide()
- func (t *Transition) IsAnimating() bool
- func (t *Transition) IsShown() bool
- func (t *Transition) Layout(ctx widget.Context, constraints geometry.Constraints) geometry.Size
- func (t *Transition) Show()
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Direction ¶
type Direction uint8
Direction specifies the origin or target edge for slide effects.
const ( FromTop Direction = iota // Slide in from top edge. FromBottom // Slide in from bottom edge. FromLeft // Slide in from left edge. FromRight // Slide in from right edge. ToTop // Slide out toward top edge. ToBottom // Slide out toward bottom edge. ToLeft // Slide out toward left edge. ToRight // Slide out toward right edge. )
Slide directions for enter effects (From*) and exit effects (To*).
type Effect ¶
type Effect struct {
// OpacityStart is the starting opacity. Negative means opacity is not animated.
OpacityStart float64
// OpacityEnd is the ending opacity.
OpacityEnd float64
// TranslateXFraction is the starting X offset as a fraction of widget width.
// For example, -1.0 means start one full width to the left.
TranslateXFraction float64
// TranslateYFraction is the starting Y offset as a fraction of widget height.
TranslateYFraction float64
// ScaleStart is the starting scale factor. Negative means scale is not animated.
ScaleStart float64
// ScaleEnd is the ending scale factor.
ScaleEnd float64
}
Effect describes the visual transformation applied during a transition.
Each field pair (Start/End) defines the range of animation for that property. A negative Start value means the property is not animated. Effect is a value type; create instances via the provided constructors.
func None ¶
func None() Effect
None returns an effect that performs no animation (instant transition).
func ScaleIn ¶
func ScaleIn() Effect
ScaleIn returns an effect that scales from 0.8 to 1.0 with a fade in.
func ScaleOut ¶
func ScaleOut() Effect
ScaleOut returns an effect that scales from 1.0 to 0.8 with a fade out.
func SlideIn ¶
SlideIn returns a slide-in effect from the given direction.
The widget slides from off-screen (one full dimension away) to its final position. Only From* directions are meaningful for enter effects; To* directions are treated as their From* equivalents.
type Fade ¶ added in v0.1.14
type Fade struct {
widget.WidgetBase
// contains filtered or unexported fields
}
Fade animates its child's opacity from transparent to opaque (fade-in) or opaque to transparent (fade-out).
Fade uses a background-color overlay approach: the child is drawn normally, then a rectangle with the background color at (1-opacity) alpha is drawn on top. This simulates opacity without requiring offscreen rendering or per-pixel alpha compositing.
When the canvas implements OpacityPusher, true per-pixel opacity is used instead of the overlay approach.
Create a Fade with NewFade and functional options:
fade := transition.NewFade(myWidget,
transition.FadeDuration(200 * time.Millisecond),
transition.FadeEasing(animation.EaseInOutCubic),
)
By default, the animation starts automatically on Fade.Mount (autoStart). Call Fade.FadeIn or Fade.FadeOut to trigger animations manually.
func NewFade ¶ added in v0.1.14
func NewFade(child widget.Widget, opts ...FadeOption) *Fade
NewFade creates a new Fade transition wrapping the given child widget.
The child fades from transparent to opaque on fade-in, or opaque to transparent on fade-out. By default the fade-in animation starts automatically when the widget is mounted.
fade := transition.NewFade(myWidget,
transition.FadeDuration(200 * time.Millisecond),
transition.FadeEasing(animation.EaseInOutCubic),
)
func (*Fade) Children ¶ added in v0.1.14
Children returns the wrapped child as a single-element slice.
func (*Fade) Draw ¶ added in v0.1.14
Draw renders the child with a fade effect based on current opacity.
func (*Fade) FadeIn ¶ added in v0.1.14
func (f *Fade) FadeIn()
FadeIn triggers a fade-in animation (opacity 0 to 1).
If an animation is already in progress, it is restarted from the beginning.
func (*Fade) FadeOut ¶ added in v0.1.14
func (f *Fade) FadeOut()
FadeOut triggers a fade-out animation (opacity 1 to 0).
If an animation is already in progress, it is restarted from the beginning.
func (*Fade) IsAnimating ¶ added in v0.1.14
IsAnimating reports whether a fade animation is currently in progress.
func (*Fade) Layout ¶ added in v0.1.14
Layout delegates to the child and returns its preferred size.
func (*Fade) Mount ¶ added in v0.1.14
Mount starts the auto-start fade-in animation if enabled. Implements widget.Lifecycle.
func (*Fade) SetOpacity ¶ added in v0.1.14
SetOpacity sets the opacity directly without animation. The value is clamped to [0, 1].
func (*Fade) Unmount ¶ added in v0.1.14
func (f *Fade) Unmount()
Unmount is called when the widget is removed from the tree. Implements widget.Lifecycle.
type FadeOption ¶ added in v0.1.14
type FadeOption func(*fadeConfig)
FadeOption configures a Fade widget during construction.
func FadeAutoStart ¶ added in v0.1.14
func FadeAutoStart(start bool) FadeOption
FadeAutoStart controls whether the fade-in animation starts automatically on Fade.Mount. Defaults to true.
func FadeBackground ¶ added in v0.1.14
func FadeBackground(color widget.Color) FadeOption
FadeBackground sets the background color used for the overlay approach. When the canvas does not implement OpacityPusher, the fade effect is achieved by drawing a semi-transparent rectangle of this color over the child. Defaults to white.
func FadeDuration ¶ added in v0.1.14
func FadeDuration(d time.Duration) FadeOption
FadeDuration sets the animation duration. Defaults to 200ms.
func FadeEasing ¶ added in v0.1.14
func FadeEasing(e animation.Easing) FadeOption
FadeEasing sets the easing function. Defaults to animation.EaseInOutCubic.
type OpacityPusher ¶
type OpacityPusher interface {
// PushOpacity pushes an opacity multiplier onto the draw state stack.
// Opacity is in the range [0, 1]. Nested calls multiply.
PushOpacity(opacity float64)
// PopOpacity removes the most recently pushed opacity.
PopOpacity()
}
OpacityPusher is an optional Canvas capability for opacity effects.
If the Canvas passed to Draw implements this interface, fade effects will use PushOpacity/PopOpacity. Otherwise, fade effects are silently skipped (graceful degradation).
type Option ¶
type Option func(*transitionConfig)
Option configures a Transition widget.
func Easing ¶
Easing sets the easing function for both enter and exit effects. Defaults to animation.EaseOutCubic if not set.
func EnterEffect ¶
EnterEffect sets the effect played when the widget appears.
func ExitEffect ¶
ExitEffect sets the effect played when the widget disappears.
type Slide ¶ added in v0.1.14
type Slide struct {
widget.WidgetBase
// contains filtered or unexported fields
}
Slide animates its child's position using widget.Canvas.PushTransform.
The child slides from off-screen (one full dimension away) to its natural position (slide-in), or from its natural position to off-screen (slide-out). This is useful for notification slide-ins, page transitions, and drawer animations.
Create a Slide with NewSlide and functional options:
slide := transition.NewSlide(myWidget,
transition.SlideFrom(transition.FromTop),
transition.SlideDuration(300 * time.Millisecond),
transition.SlideEasing(animation.EaseOutCubic),
)
By default, the animation starts automatically on Slide.Mount (autoStart). Call Slide.SlideIn or Slide.SlideOut to trigger animations manually.
func NewSlide ¶ added in v0.1.14
func NewSlide(child widget.Widget, opts ...SlideOption) *Slide
NewSlide creates a new Slide transition wrapping the given child widget.
The child's position is animated from off-screen to its natural position (or vice versa) based on the configured direction. By default the animation starts automatically when the widget is mounted.
slide := transition.NewSlide(myWidget,
transition.SlideFrom(transition.FromTop),
transition.SlideDuration(300 * time.Millisecond),
)
func (*Slide) Children ¶ added in v0.1.14
Children returns the wrapped child as a single-element slice.
func (*Slide) Draw ¶ added in v0.1.14
Draw renders the child with a translation offset based on animation progress.
func (*Slide) IsAnimating ¶ added in v0.1.14
IsAnimating reports whether a slide animation is currently in progress.
func (*Slide) Layout ¶ added in v0.1.14
Layout delegates to the child and returns its preferred size.
func (*Slide) Mount ¶ added in v0.1.14
Mount starts the auto-start animation if enabled. Implements widget.Lifecycle.
func (*Slide) Progress ¶ added in v0.1.14
Progress returns the current animation progress (0.0 to 1.0).
For slide-in: 0 = fully offscreen, 1 = fully visible. For slide-out: 0 = fully visible, 1 = fully offscreen.
func (*Slide) SlideIn ¶ added in v0.1.14
func (s *Slide) SlideIn()
SlideIn triggers a slide-in animation (offscreen to natural position).
If an animation is already in progress, it is restarted from the beginning. The child becomes visible immediately.
func (*Slide) SlideOut ¶ added in v0.1.14
func (s *Slide) SlideOut()
SlideOut triggers a slide-out animation (natural position to offscreen).
If an animation is already in progress, it is restarted from the beginning.
func (*Slide) Unmount ¶ added in v0.1.14
func (s *Slide) Unmount()
Unmount is called when the widget is removed from the tree. Implements widget.Lifecycle.
type SlideOption ¶ added in v0.1.14
type SlideOption func(*slideConfig)
SlideOption configures a Slide widget during construction.
func SlideAutoStart ¶ added in v0.1.14
func SlideAutoStart(start bool) SlideOption
SlideAutoStart controls whether the animation starts automatically on Slide.Mount. Defaults to true.
func SlideDuration ¶ added in v0.1.14
func SlideDuration(d time.Duration) SlideOption
SlideDuration sets the animation duration. Defaults to 300ms.
func SlideEasing ¶ added in v0.1.14
func SlideEasing(e animation.Easing) SlideOption
SlideEasing sets the easing function. Defaults to animation.EaseOutCubic.
func SlideFrom ¶ added in v0.1.14
func SlideFrom(dir Direction) SlideOption
SlideFrom sets the direction from which the child slides in. Defaults to FromTop.
func SlideReverse ¶ added in v0.1.14
func SlideReverse(rev bool) SlideOption
SlideReverse makes the auto-start animation slide OUT instead of IN. When true and autoStart is enabled, the widget starts visible and slides out on Mount. Defaults to false.
type Transition ¶
type Transition struct {
widget.WidgetBase
// contains filtered or unexported fields
}
Transition wraps a child widget with enter/exit animation effects.
When Show is called, the enter effect is played and the child becomes visible. When Hide is called, the exit effect is played and the child is hidden after the animation completes.
Transition implements widget.Widget.
func Wrap ¶
func Wrap(child widget.Widget, opts ...Option) *Transition
Wrap creates a new Transition that wraps the given child widget.
By default the widget starts visible with no animation effects. Use EnterEffect, ExitEffect, Duration, and Easing options to configure the transition behavior.
wrapped := transition.Wrap(myWidget,
transition.EnterEffect(transition.FadeIn()),
transition.ExitEffect(transition.FadeOut()),
transition.Duration(300 * time.Millisecond),
)
func (*Transition) Child ¶
func (t *Transition) Child() widget.Widget
Child returns the wrapped child widget.
func (*Transition) Children ¶
func (t *Transition) Children() []widget.Widget
Children returns the wrapped child as a single-element slice.
func (*Transition) Draw ¶
func (t *Transition) Draw(ctx widget.Context, canvas widget.Canvas)
Draw renders the child widget with transition effects applied.
func (*Transition) Hide ¶
func (t *Transition) Hide()
Hide hides the widget, playing the exit effect if configured.
If an enter animation is currently playing, it is replaced by the exit animation starting from the beginning.
func (*Transition) IsAnimating ¶
func (t *Transition) IsAnimating() bool
IsAnimating reports whether a transition animation is currently in progress.
func (*Transition) IsShown ¶
func (t *Transition) IsShown() bool
IsShown reports whether the widget is logically visible (enter complete or in progress). Returns false if hidden or exit animation is complete.
func (*Transition) Layout ¶
func (t *Transition) Layout(ctx widget.Context, constraints geometry.Constraints) geometry.Size
Layout calculates the transition widget size by delegating to the child.
func (*Transition) Show ¶
func (t *Transition) Show()
Show makes the widget visible, playing the enter effect if configured.
If an exit animation is currently playing, it is replaced by the enter animation starting from the beginning.
Source Files