Skip to main content
Version: 2.1

Animation somewm-only

SomeWM animates client geometry, panel visibility and selected widget properties. Durations are in seconds. The configuration differs by object:

ObjectSettingWhat it does
Wibox, popup or wibarpanel.animation.visibleAnimates the panel's frame when it appears, disappears, moves or resizes.
Widget, container or layoutwidget.animationAnimates selected property changes, such as a background colour or requested width.
Application windowc.animationAnimates events such as opening, closing, changing focus or moving between tiled positions.
All objectssomewm.animation.enabledEnables or disables animation globally.

Properties select what changes. Effects select how an object appears or disappears. Neither sets the target size, position or colour; those values still come from the object's properties and layout.

For working examples, see Animate clients, popups and widgets.

Panels: panel.animation.visible​

Applies to awful.popup, awful.wibar and wibox objects. visible is the only accepted key in panel.animation. It controls animation when the panel appears, disappears or changes while visible.

panel.animation = {
visible = {
duration = 0.3,
properties = { "width" },
},
}
panel.width = 300

On an already drawn wibox, this animates its width from the displayed value to 300 logical pixels over 0.3 seconds. An awful.popup derives its size from its contents and constraints; see Animate a viewport for a popup example.

Configuration fields​

FieldTypeDefaultDescription
durationnumber0Duration in seconds, from 0 to 1,000,000. Applies to appearance, disappearance and changes while visible. No theme fallback.
enterstring or nonempty listUnsetEffect when the panel appears.
exitstring or nonempty listUnsetEffect when the panel disappears. Removal is immediate without an exit effect.
exit_orderstring"natural"Drawing order during disappearance. Values listed below.
propertiesstring or nonempty listDepends on effectsSelects which frame changes animate over duration. Other changes apply immediately, subject to the effect rules below.

exit_order values

ValueDescription
"above"Draws the disappearing item above its siblings.
"natural"Preserves its drawing order among siblings.
"underneath"Draws the disappearing item below its siblings.

exit_order does not change the panel's stacking layer.

Additional accepted fields

FieldTypeDefaultBehaviour on panels
exit_durationnumberdurationNo separate timing effect. Exits use duration.
tag_durationnumberdurationNo separate timing effect. Tag-departure timing applies only to client declarations.
tag_exitstring or nonempty listUnsetExit effect used when exit is absent. Does not attach the panel to a tag.

Animated properties​

panel.animation.visible.properties accepts a string or a nonempty list of strings. Unselected properties change immediately, except where an effect adds them.

Size and position

ValueAnimated propertiesWhat it does
"box"Position, width and heightMoves and resizes the frame together when its geometry changes.
"height"HeightExpands or contracts the frame vertically to its new height. Width and position changes apply immediately.
"position"Horizontal and vertical positionMoves the frame to its new location. Size changes apply immediately.
"size"Width and heightExpands or contracts the frame in both dimensions. Position changes apply immediately.
"width"WidthExpands or contracts the frame horizontally to its new width. Height and position changes apply immediately.

These rows describe each selector used alone. A list combines them; { "position", "width" } animates movement and horizontal resizing while height changes apply immediately.

Appearance

ValueAnimated propertiesWhat it does
"background"Frame background colourBlends from the old fill colour to the new one. Does not affect a background drawn separately inside the frame.
"border"Border colour and thicknessBlends the outline colour and thickens or thins the outline together.
"border_color"Border colourBlends from the old outline colour to the new one. Thickness changes apply immediately.
"border_width"Border thicknessThickens or thins the outline to its new width. Colour changes apply immediately.

Custom shapes restrict these animations; see Panel limits.

Unsupported values

ValueBehaviour
"bg"Invalid. Background widgets use widget.animation.bg.
"corner_radius"Accepted with a warning. Radius changes are immediate.
"forced_width"Invalid. Widgets use widget.animation.forced_width.
"opacity"Invalid. Visibility fading uses the fade effect.
"x", "y"Invalid. Use "position" for both axes.

Default animated properties​

When properties is omitted, enter and exit determine what animates.

EffectDefault animated propertiesChanges while visible
No effect or "none"Position, width and heightMoves and resizes the frame over duration. "none" disables the appearance or disappearance effect, not these geometry animations.
"fade"TransparencySize and position changes apply immediately. Add properties to animate them too.
"grow" or "collapse"Width and heightResizes the frame over duration. Position changes apply immediately.
Any scale effectDisplayed scaleSize and position changes apply immediately. The visibility effect scales the image without changing layout size.
Any slide effectPositionMoves the frame over duration. Size changes apply immediately.
Combined effectsAll properties required by the selected effectsFor example, fade with slide_left also animates position changes.

An explicit properties list restricts grow to the selected dimensions. Slide effects always add position. Fade and scale effects still apply with an explicit list. tag_exit does not determine these defaults.

Panel limits​

PropertyLimit
Background colour"background" does not animate panel.bg when the background is drawn separately from the frame. A background widget can animate its own bg.
Border colour and thicknessCustom shape paths change these immediately. Path-shaped panel borders also render nonzero red, green and blue channels at full intensity. For example, #83a598 renders white.
Width and heightResizing does not keep the contents at a fixed size. The viewport example supplies that constraint. Borders follow the changing frame size, including custom shapes.

Effects​

Accepted by panel enter and exit, client appear, disappear and tag, and the corresponding theme fields. An effect describes the starting state when appearing and the final state when disappearing.

Visibility

ValueOn appearanceOn disappearance
"fade"Fades from transparent to the object's configured opacity.Fades to transparent.
"none"Appears immediately.Disappears immediately.

Size

ValueOn appearanceOn disappearance
"collapse"Same as "grow".Same as "grow".
"grow"Expands the frame from zero to its target size.Contracts the frame to zero size.
"scale"Enlarges the entire image from zero around its centre.Shrinks the image into its centre.
"scale_bottom"Enlarges the image with its bottom edge's midpoint fixed.Shrinks the image into its bottom edge's midpoint.
"scale_left"Enlarges the image with its left edge's midpoint fixed.Shrinks the image into its left edge's midpoint.
"scale_right"Enlarges the image with its right edge's midpoint fixed.Shrinks the image into its right edge's midpoint.
"scale_top"Enlarges the image with its top edge's midpoint fixed.Shrinks the image into its top edge's midpoint.

grow changes width and height. On panels, an explicit properties list restricts it to the selected dimensions: properties = "width" produces a horizontal expansion or contraction. Scale effects preserve layout size and scale the contents with the frame. Pointer targeting follows the displayed size and position.

Position

ValueOn appearanceOn disappearance
"slide_down"Moves in from the screen's bottom edge.Moves out towards the screen's bottom edge.
"slide_left"Moves in from the screen's left edge.Moves out towards the screen's left edge.
"slide_right"Moves in from the screen's right edge.Moves out towards the screen's right edge.
"slide_up"Moves in from the screen's top edge.Moves out towards the screen's top edge.

Effect lists

CombinationBehaviour
One slide, one size effect and fadeRun together with one duration. Any subset is accepted.
Repeated effectNo additional effect.
Multiple slides or multiple size effectsWarns and keeps the first effect in that group.
none with another effectWarns and keeps the first choice.

Widgets: widget.animation​

Each entry maps a property name to a duration in seconds. Only named properties animate. Theme durations do not enable widget animation.

box.animation = { bg = 0.3, forced_width = 0.2 }
box.bg = "#ff0000"
box.forced_width = 300

Here box is a wibox.container.background that has already been drawn. The fill blends to red and the widget resizes to the width allowed by its layout. Properties drawn as one item share the longest duration; see Widget limits.

PropertyAvailable onWhat it does
bgwibox.container.backgroundBlends the solid fill from its previous colour to the newly assigned bg.
border_colorwibox.container.backgroundBlends the outline from its previous colour to the newly assigned border_color.
border_widthwibox.container.backgroundThickens or thins the outline to the newly assigned border_width.
forced_heightSupported widgets, containers and layoutsExpands or contracts the widget vertically when its requested height changes, subject to the surrounding layout's sizing rules.
forced_widthSupported widgets, containers and layoutsExpands or contracts the widget horizontally when its requested width changes, subject to the surrounding layout's sizing rules.
valuewibox.widget.progressbar, wibox.widget.sliderLengthens or shortens the filled portion of the bar to represent the new value. A slider's handle moves immediately.

Widget limits​

ConditionBehaviour
First appearanceImmediate. Animation applies to later changes.
Multiple properties drawn as one itemAll use the longest configured duration, including properties assigned 0. A progressbar or slider's fill can have a separate duration.
Gradient backgroundbg changes warn and apply immediately.
Custom shape pathbg, border_color and border_width changes warn and apply immediately. Solid rounded rectangles support these animations.
Unsupported property nameWarns and changes immediately. Includes visible, x, y and shape.
Layout spacing changeMoves children immediately. Their selected sizes can still animate.

widget:animate(args)​

Animates one change. Available on widgets, not clients, wiboxes or popups.

ArgumentTypeRequiredDescription
durationnumberYesDuration in seconds, from 0 to 1,000,000.
Property namesProperty-specific valuesNoNew values to assign. Supported animations are listed in widget.animation.

Setters run immediately. widget.animation remains unchanged. Later assignments use those settings, or change immediately when none are set. Disabling animation does not prevent :animate from assigning its values.

Clients: c.animation​

Applies to application windows. Also accepted as animation in a client rule's properties table.

c.animation = { layout = 0.15, focus = 0.1 }

This client moves and resizes over 0.15 seconds when its layout changes. Focus border colours blend over 0.1 seconds if the configuration changes them.

EventAccepted valueDescription
appearDuration, effect, effect list or falseFirst appearance. Requires an effect to animate.
disappearDuration, effect, effect list or falseClosing. Requires an effect to animate. The remaining frame, including the border and titlebars, can animate. The client content disappears on the first frame.
floatingDurationMoves and resizes the window to its new geometry when switching between floating and tiled states.
focusDurationFocus changes. Animates border colour if the configuration changes it.
layoutDurationMoves and resizes tiled windows into their new positions, including tiled resizing and carousel scrolling.
maximizeDurationMoves and resizes the window when entering or leaving maximised or fullscreen states.
tagDuration, effect, effect list or falseVisibility changes on tag/view changes. Default effect is grow.

Values for appear, disappear and tag

ValueDurationEffect
NumberSupplied number of seconds.Theme effect, with grow as the tag fallback.
Effect name or listTheme duration.Supplied effect or list.
falseTheme duration still applies.Disables this event's effect, including the theme effect and tag fallback.

Nested tables such as appear = { duration = 0.3 } are invalid. Simultaneous geometry and focus changes use the longer duration.

Theme variables​

Fields on the table returned by theme.lua, or on beautiful after loading the theme. Apply to clients, not panels or widgets.

VariableTypeDefaultWhat it does
animation_appearstring or nonempty listUnsetSelects how a new window appears, such as fading in or sliding in from an edge.
animation_appear_durationnumberUnsetSets how many seconds the appearance effect takes. Requires an appearance effect.
animation_disappearstring or nonempty listUnsetSelects how a closing window's remaining frame disappears.
animation_disappear_durationnumberUnsetSets how many seconds the disappearance effect takes. Requires a disappearance effect.
animation_durationnumberUnsetSupplies a duration in seconds for client events without a more specific duration.
animation_floating_durationnumberUnsetSets how long the window moves and resizes when switching between floating and tiled states.
animation_focus_durationnumberUnsetSets how long the border blends to its new colour when focus changes.
animation_layout_durationnumberUnsetSets how long tiled windows move and resize after a layout change or carousel scroll.
animation_maximize_durationnumberUnsetSets how long the window moves and resizes when entering or leaving maximised or fullscreen states.
animation_tagstring or nonempty list"grow"Selects how windows enter and leave the view when switching tags.
animation_tag_durationnumberUnsetSets how many seconds the tag appearance and disappearance effects take.

All durations are in seconds. An unset duration uses the next fallback below; an effect alone does not enable animation.

Duration precedence, first match wins

  1. Numeric c.animation[event].
  2. beautiful.animation_<event>_duration.
  3. beautiful.animation_duration.
  4. somewm.animation.layout_duration for layout, otherwise 0.

An explicit 0 stops the fallback search. Effects use the object's setting before the theme, with grow as the tag fallback.

Global settings: somewm.animation​

Accessed with require("somewm.animation").

PropertyTypeDefaultDescription
enabledbooleantrueEnables all animations. Setting false completes active animations on the next drawn frame. Re-enabling affects future changes only.
layout_durationnumber0Sets how many seconds client layout movement and resizing take when neither the object nor the theme supplies a duration.

Requiring the deprecated somewm.layout_animation module sets layout_duration to 0.15. Its duration and enabled fields read and write the corresponding settings above.

Assignment and disabling​

AssignmentBehaviour
object.animation = tableCopies and applies valid settings. Emits property::animation and requests an update.
object.animation = falseDisables the object and all widgets inside it, including a client's titlebar widgets.
object.animation = nilRemoves local settings. Client theme defaults and settings on contained widgets can apply again, unless an ancestor disables animation.
Duration of 0Applies changes immediately. Does not disable contained widgets. Properties drawn as one widget item still share the longest duration.

Reading a valid .animation settings table returns a copy. Changing that copy has no effect until it is assigned back to .animation. Invalid tables are preserved by reference; see Validation and runtime limits.

Custom descriptions: transition​

Available on an element in a custom widget or client-layout description. Accepts the same fields, properties and effects as panel.animation.visible.

Setting or conditionBehaviour
Changes to w, h, bg and other selected fieldsSupply new values for that element's animation.
Element identityMust remain stable between descriptions to animate the same element.
Element removalAn exit effect keeps it drawn until the animation finishes. It no longer reserves layout space.
exit_durationSeparate duration for client disappearance only. Other elements use duration.
tag_durationSeparate duration for client tag departure only. Other elements use duration.

Validation and runtime limits​

Setting or conditionContract
.animation typeAccepts a table, false or nil. Other value types raise an error. Only plain tables without a metatable can supply animation settings.
Wrong table structure or table with a metatablePreserved by reference without enabling animation. Warns once per object. Clients can still use theme defaults.
Invalid panel field valueUnknown property name, effect, exit order or out-of-range duration in a correctly structured table raises an error on assignment.
Invalid client or widget descriptionRejected when compiled for drawing.
DurationSeconds from 0 to 1,000,000.
Timing curveStarts faster and slows near the end. Not configurable.
Additional timing controlsNo delay, easing, repeat, on_complete or on_update fields.
Animation capacity200 drawing elements per screen, including configured elements waiting for changes. Warns when full. Additional elements change immediately.
Active mousegrabberSuppresses animation during the grab. Changes apply immediately.
Lua property readbackReturns the requested final value, including while animation is running. The tree dump shows current displayed geometry.
GeometryRounded to whole logical pixels.

See also​