Skip to main content
Version: 2.2 (dev)

Signals

Signals are grouped by the object or module that emits them. See signal concepts for connecting handlers and replacing defaults.

Dispatch​

The C-generated signals listed below are queued and drained at some_refresh(). Other C-generated signals and all Lua-emitted signals run synchronously. See Signals (concepts): Dispatch model for the model and the implications.

Currently queued:

  • Property: property::geometry, property::position, property::size, property::x, property::y, property::width, property::height, property::active, property::border_color
  • Focus: focus, unfocus, client::focus, client::unfocus
  • Mouse: mouse::enter, mouse::leave, mouse::move (coalesced per object)
  • Lifecycle: list, swapped
  • Request: request::activate, request::urgent
  • Systray: request::secondary_activate, request::context_menu, request::scroll
  • Output: property::enabled, property::scale, property::transform, property::mode, property::adaptive_sync, property::screen (screen attached), and the output class added
  • Screen: property::scale, property::geometry, property::workarea, primary_changed, and the screen class list and property::_viewports
  • Layer shell: property::layer, property::anchor, property::exclusive_zone, property::keyboard_interactive, property::margin
  • Globals: xkb::map_changed, xkb::group_changed, idle::stop, dpms::on, spawn::timeout, spawn::completed, switch::toggle, screen::focus, client::map, client::unmap, client::property::geometry

Dispatch depends on the emitter, not only the signal name. Every Lua emit_signal() runs inline. These C paths also run inline:

PathSignals
Client lifecyclerequest::manage, request::unmanage, scanning, scanned
Client requests and scalar propertiesrequest::geometry, property::name, property::fullscreen, and other properties absent from the queue list
Screen lifecycleadded, removed, request::focus_restore
Lua screen operationsfake_add/fake_remove deliver list, swap delivers list and swapped, setting screen.primary delivers primary_changed
Output teardownremoved, and property::screen when detaching the screen
Lua output settersProperty notifications from the setter, apart from the queued screen geometry updates it causes
Input and layer lifecycleKey/button and grabber callbacks, layer manage/unmanage and keyboard requests
Idle, power, and sleepidle::start before its timeout callback, awesome.dpms_on() notifications, logind::prepare_sleep before suspend

Wibar changes take effect during layout. property::workarea is queued after Clay solves the new workarea, not emitted inline by the wibar setter.

D-Bus method handlers also run inline. request::tag and request::select are Lua-emitted and synchronous.

State before a queued handler runs​

The queue drains before refresh and layout. An object's state can change before its queued handlers run. For example, client.focus may already name the new client while focus history still reflects the previous event. Use gears.timer.delayed_call() when a read needs to follow those handlers.

Queued arguments retain their emitted values, but reading the object returns its current state. Events for screens or outputs removed before delivery are dropped. Only valid remains readable on these invalid objects, and screen[s] returns nil for a removed screen.

client signals​

Connect with client.connect_signal("name", handler). Instance signals pass the client as the first argument. Class signals such as scanning do not.

Lifecycle​

SignalArgsNotes
request::managec, context, hintsA new client wants to be managed. Default handlers (in awful.permissions, ruled.client) tag it, place it, and apply rules. Class-handler connection order does not guarantee execution order. Use a rule callback to read post-rule properties. context is "new" or "startup".
request::unmanagec, context, hintsThe client is going away. Default handlers do final cleanup. context is "user", "reparented", or "destroyed". The client is still valid and its geometry and screen are readable, but its tags have already been detached.
scanningnoneCompositor is enumerating already-running clients before any are managed. ruled.client emits request::rules from here.
scannednoneInitial scan is complete. Fires before awesome.startup callbacks.

Focus and stacking​

SignalArgsNotes
focuscClient gained focus.
unfocuscClient lost focus. Fires before focus on the new client.
raisedcClient moved to top of its layer (see Client Stacking).
loweredcClient moved to bottom of its layer.

Properties​

Each property::* fires after the property changes. Read the new value off the client.

SignalNotes
property::shapeClient shape changed.
property::content_radiusContent radii changed, or the property switched between numeric and table forms. See Client corners.
property::animationAnimation policy assigned.
property::size_hintsSize hints changed, including committed Wayland min/max bounds.
property::border_colorBorder colour changed, including focus recolouring.
property::nameTitle changed.
property::classClass changed (usually at startup).
property::geometrySize or position changed.
property::floatingFloating state toggled.
property::fullscreenFullscreen toggled.
property::ontopAbove-everything layer toggled.
property::aboveAbove-normal layer toggled.
property::belowBelow-normal layer toggled.
property::urgentUrgency hint changed. Check c.urgent inside the handler. Fires for both true and false.

Requests​

request::* signals ask handlers to do something. Replace a default handler by disconnecting it and connecting your replacement. See Replacing a default handler.

SignalArgsNotes
request::activatec, context, hintsSomething asked for the client to become active (focused/raised). Default handler in awful.permissions.activate.
request::titlebarsc, context, hintsClient should grow titlebars. Connect to draw them (or skip drawing to opt out).
request::geometryc, context, hintsClient (or another module) asked to be moved/resized. context says why ("maximized_horizontal", "fullscreen", etc.).
request::tagc, tag_or_true, hintsClient needs a tag (after creation, after losing its screen). Default handler: awful.permissions.tag. A true second argument requests sticky state. hints.reason can be "screen", "screen-removed", "rules".
request::borderc, context, hintsClient wants its border restyled. Default handler: awful.permissions.update_border. context is one of "added", "active", "inactive", "floating", "urgent", "maximized", "fullscreen".
request::urgentc, urgentApplication requested an urgency change. The default handler decides whether to set c.urgent.
request::default_keybindingscontext (string)Class signal emitted once at startup. Connect to register default keybindings via awful.keyboard.append_client_keybindings.
request::default_mousebindingscontext (string)Class signal emitted once at startup. Connect to register default mousebindings via awful.mouse.append_client_mousebindings.

screen signals​

SignalArgsNotes
addedsNew output connected.
removedsOutput disconnected. Tags on this screen will get request::screen next.
request::desktop_decorationsScreen needs tags and wibars. Your handler creates them. See Tag Persistence.
request::wallpapersScreen wants its wallpaper drawn. The default handler builds it with awful.wallpaper.
request::focus_restoresSomething that had focus went away (client closed, layer surface dismissed, session unlocked, monitor disconnected). Default handler: awful.permissions.focus_restore, which activates the most recent visible client from focus history. If no handler focuses a client, C tries the topmost eligible client on the monitor. somewm-only
property::geometrys, old_geometryScreen geometry changed (resolution or layout).
property::workareas, old_workareaWorkarea (geometry minus struts) changed. Fires when wibars appear or resize.
property::scalesOutput scale changed. somewm-only
property::inspectorsInspector opened or closed. somewm-only
property::outputssOutput metadata (model, make, refresh) changed.

tag signals​

Connect with tag.connect_signal("name", handler). Handlers receive the tag.

SignalArgsNotes
request::screent, reasonTag's screen was removed and it needs a new one. Default handler: awful.permissions.tag_screen. See Tag Persistence.
request::default_layoutscontext (string)Class signal emitted once at startup. Connect to register layouts via awful.layout.append_default_layouts.
property::selectedtTag was selected or deselected.
property::activatedtTag was added to or removed from a screen.
taggedt, cClient added to tag.
untaggedt, cClient removed from tag.

ruled.client signals​

Module-level signals on ruled.client. Connect with ruled.client.connect_signal(...).

SignalArgsNotes
request::rulesnoneFires once on client.scanning, after all modules are loaded but before any client is managed. Call ruled.client.append_rule() here before client matching begins. See Defer startup with request::rules.

ruled.notification signals​

Module-level signals on ruled.notification.

SignalArgsNotes
request::rulesnoneFires from awesome.startup. Register rules with ruled.notification.append_rule().

naughty signals​

SignalArgsNotes
addednA notification was created.
destroyedn, reasonA notification was destroyed. reason matches naughty.notification_closed_reason.*.
request::displaynNaughty wants this notification rendered. Connect a handler that builds a notification widget. See Notifications.
request::action_iconaAn action wants its icon resolved.

See the naughty reference for the full set.

Overflow layout signals​

SignalArgsNotes
property::scroll_factorlayout, factorA frame applied a changed scroll factor, including wheel input and content or viewport changes.

Layer surface signals somewm-only​

SignalArgsNotes
request::managel, context, hintsA layer-shell surface appeared.
request::unmanagel, context, hintsA layer-shell surface is closing.
request::keyboardl, context, hintsLayer surface wants keyboard interactivity.
property::has_keyboard_focuslKeyboard focus on the layer surface changed.

See layer_surface reference for context.

Lock signals somewm-only​

SignalArgsNotes
lock::activatesource (string)Session locked via awesome.lock(). source is always "user".
lock::deactivatenoneSession unlocked.
lock::auth_failednonePassword authentication failed.

Idle signals somewm-only​

SignalArgsNotes
idle::startnoneFirst idle timeout fired.
idle::stopnoneActivity detected after being idle.
property::idle_inhibitednoneCombined idle inhibition state changed.

DPMS signals somewm-only​

SignalArgsNotes
dpms::offnoneAt least one display entered sleep.
dpms::onnoneAt least one display woke up.

See Lock, Idle, and DPMS reference.

awesome signals​

Global signals on awesome.*. Connect with awesome.connect_signal(...).

SignalArgsNotes
startupnoneSomeWM finished starting. Fires after client.scanned. Safe to assume all default handlers are connected.
exitrestart (boolean)SomeWM is shutting down. restart is true for a Lua hot reload in the same process.
refreshnoneAbout to redraw. Avoid expensive work in this handler. It fires often.
debug::errormsgAn uncaught Lua error occurred. Default handler logs to stderr.

Example usage​

local gears = require("gears")

client.connect_signal("focus", function(c)
gears.timer.delayed_call(function()
if c.valid then print(c.name) end
end)
end)

See also​