Skip to main content
Version: 2.1

gears

gears provides timers, drawing utilities, and file, string, and table helpers.

Upstream documentation: The gears library spans multiple sections in the AwesomeWM docs:

Key Modules​

ModulePurpose
gears.timerPeriodic and one-shot timers
gears.shapeDrawing shapes (rounded rectangles, circles, etc.)
gears.colorColor parsing and manipulation
gears.surfaceCairo surface helpers
gears.filesystemFile and directory utilities
gears.stringString manipulation
gears.tableTable utilities
gears.mathMath 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
  • load keeps a weak cache by file path. Calls can share a surface while it remains in memory. Use load_uncached after 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.surface accept 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.