Skip to main content
Version: 2.2 (dev)

awful.accessibility

awful.accessibility provides a pointer locator. It can display static or shrinking rings, temporarily enlarge a themed cursor, or combine both effects. Activation is an explicit Lua call or an optional shake gesture. Loading awful does not enable shake detection or start a locator.

Usage​

local a11y = awful.accessibility {
cursor_finder_effect = "both",
cursor_finder_shake_enabled = true,
}

awful.keyboard.append_global_keybindings {
awful.key({modkey}, "c", function() a11y:find_cursor() end,
{description = "find pointer", group = "accessibility"}),
}

The module-level awful.accessibility.find_cursor() uses a default instance. Without theme overrides it displays rings. awful.accessibility.stop_cursor_finder() stops that default instance only.

Reduced motion and persistent cursor size​

root.cursor_size(48)

local a11y = awful.accessibility {
cursor_finder_effect = "both",
cursor_finder_shake_enabled = true,
cursor_finder_animated = false,
}

With cursor_finder_animated = false, rings keep their size and opacity while following the pointer, then disappear after cursor_finder_duration seconds. Magnification changes immediately and restores the base size immediately after cursor_finder_deflate_delay seconds of inactivity. Inflation and deflation durations are ignored. Repeated activation restarts the lifetimes and adds magnification up to the configured maximum.

This setting controls pointer-locator animation only. A keyboard binding can activate the same effects without a shake gesture.

root.cursor_size(48) sets the base cursor size; placing it in rc.lua reapplies it when the configuration loads. XCURSOR_SIZE=48 in the compositor's startup environment also sets the base size. Temporary magnification multiplies the configured base size on each output; completion and cancellation restore that base, including when it is larger than the default. Cursor themes may provide discrete image sizes. Client-uploaded cursors remain application-controlled. See Cursor theming.

Constructor​

local a11y = awful.accessibility { ... }

The argument table accepts the properties below. Unknown properties and values outside the documented ranges raise an error.

A property reads its instance override, then the matching beautiful theme variable, then the default. Assigning nil removes the instance override. An explicit false remains an override. Every property has a theme variable named by prefixing it with accessibility_, for example beautiful.accessibility_cursor_finder_color.

Theme values are read when properties are accessed. Assign a11y.cursor_finder_shake_enabled to change the motion subscription of an existing instance; changing a theme variable alone does not reconnect it.

Properties​

All durations are in seconds. Distances are in logical pixels. Magnification factors are relative to the cursor's normal size on its output.

PropertyDefaultMeaning and accepted values
cursor_finder_enabledtrueBoolean; assigning false ends this instance's active locator and suppresses activation.
cursor_finder_effect"rings""rings", "magnify", or "both". Changing it ends the active locator.
cursor_finder_animatedtrueBoolean; false holds static rings and changes magnification immediately. Changing it ends the active locator.
cursor_finder_duration0.8Ring display duration, 0.01–60, for animated and static rings.
cursor_finder_radius100Largest ring's initial radius, 1–512.
cursor_finder_color"#ff6600"Solid ring colour.
cursor_finder_line_width3Ring stroke width, 1–64.
cursor_finder_ring_count2Number of concentric rings, integer 1–8.
cursor_finder_shake_enabledfalseBoolean; observe pointer motion for shakes.
cursor_finder_magnification3Initial enlargement, 1–16, limited by cursor_finder_max_scale.
cursor_finder_over_magnification1Additional enlargement per repeated activation, 0–15.
cursor_finder_max_scale4Maximum enlargement, 1–16. Values above 4 can upscale the cached image.
cursor_finder_inflate_duration0.2Time to reach an enlarged size, 0–60; 0 applies it immediately.
cursor_finder_deflate_duration1Time to return to normal size, 0–60; 0 applies it immediately.
cursor_finder_deflate_delay1.5Inactivity before deflation begins, 0.01–60.
cursor_finder_history_window1Motion-history window for shake detection, 0.01–10.
cursor_finder_sensitivity4Required ratio of travelled distance to the motion bounds' diagonal, 1–100. Larger values require more reversals.
cursor_finder_min_diagonal100Minimum diagonal of the motion bounds, 1–4096.
cursor_finder_cooldown0.5Shake suppression after deflation begins or the locator stops, 0–60.

Methods​

a11y:find_cursor()​

Starts the selected effects unless the instance is disabled. An explicit call also works when shake detection is disabled and is not suppressed by the shake cooldown.

Repeated activation restarts the rings, adds to magnification up to its maximum, and resets the deflation delay. Direction changes during continued shaking also extend that delay. Rings finish after their own duration; with both effects, magnification can remain active after the rings disappear.

a11y:stop_cursor_finder()​

Cancels this instance's timers and rings and immediately restores normal cursor size if this instance owns the active locator. Shake detection remains enabled if configured; setting cursor_finder_shake_enabled = false disables it.

Signals​

SignalArguments after the instanceEmission
cursor_finder::startNoneOnce when the locator becomes active. Repeated activation does not emit another start.
cursor_finder::endNoneOnce when the active locator completes, is stopped, is disabled, or another instance takes over.
property::<name>Effective valueWhen a property assignment changes its effective value.

Pointer and instance behaviour​

Only one locator owns the pointer at a time. Activating another instance stops the previous one. If an end-signal handler activates a locator, that later activation takes precedence over the interrupted request. Calling stop_cursor_finder() on an inactive instance does not affect the active instance. Enabling shake detection on another instance disables it on the previous observer and emits its property-change signal.

Rings pass input through and follow pointer motion. The cursor hotspot stays at the pointer throughout enlargement. Themed cursors, including shapes requested by applications through the cursor-shape protocol, can enlarge. Client-uploaded cursor surfaces retain their normal size; a client hiding its cursor remains hidden. An uploaded cursor resets magnification so returning to the desktop does not reveal an accumulated enlargement.

Pointer locking prevents shake detection from receiving movement. Ordinary pointer grabs do not prevent observation. Coordinate warps alone do not count as shake samples. Restarting the configuration clears the locator and restores normal magnification.

Magnification uses the output frame clock and cached cursor images. Shake detection observes motion events; it does not poll while the pointer is idle.