gears
gears provides timers, drawing utilities, and file, string, and table helpers.
Upstream documentation: The gears library spans multiple sections in the AwesomeWM docs:
- theme_related_libraries - shape, color
- utility_libraries - timer, filesystem, string, table
Key Modules
| Module | Purpose |
|---|---|
gears.timer | Periodic and one-shot timers |
gears.shape | Drawing shapes (rounded rectangles, circles, etc.) |
gears.color | Color parsing and manipulation |
gears.surface | Cairo surface helpers |
gears.filesystem | File and directory utilities |
gears.string | String manipulation |
gears.table | Table utilities |
gears.math | Math helpers |
Common Patterns
Timers
local gears = require("gears")
-- Repeating timer
local mytimer = gears.timer({
timeout = 60,
autostart = true,
callback = function()
-- runs every 60 seconds
end
})
-- One-shot delayed call
gears.timer.delayed_call(function()
-- runs once on next iteration
end)
Shapes
local gears = require("gears")
local wibox = require("wibox")
local widget = wibox.container.background()
widget.shape = function(cr, w, h)
gears.shape.rounded_rect(cr, w, h, 8)
end
Surfaces
gears.surface turns image files into cairo surfaces, used by bgimage, wallpapers, and icons:
local gsurface = require("gears.surface")
local path = require("gears.filesystem").get_themes_dir() .. "default/background.png"
local img = gsurface.load(path) -- cached by path
local img2 = gsurface.load_uncached(path) -- fresh copy, no cache
local w, h = gsurface.get_size(img) -- pixel dimensions
loadkeeps a weak cache by file path. Calls can share a surface while it remains in memory. Useload_uncachedafter replacing the file or when you need a separate surface to modify.- A path that fails to load is not an error: an error is printed to the log and an empty 0x0 surface is returned, which draws nothing. If an image silently does not appear, check the log.
- Passing an existing cairo surface returns it unchanged, so APIs built on
gears.surfaceaccept either a path or a surface.
Behavioral Notes
gears.wallpaper is unavailable. Use awful.wallpaper for wallpapers. The Cairo utilities use the AwesomeWM API. See deviations for compositor-specific behaviour, including wallpaper rendering.