Signals

Awesome 3.4 added signals as a new mechanism for managing events. It replaces the old hook system and some other functions like widget.mouse_enter.

Instead of:

mytextbox.mouse_leave = function --CODE end

One now uses in Awesome 3.5:

mytextbox:connect_signal("mouse::leave", function      --CODE  end)

Awesome 3.4 uses "add_signal" instead of "connect_signal" in 3.5.

You can add or remove handler functions to be called when a signal is emitted. Multiple handlers can be bound to the same signal. You can also tell objects to emit signals by hand, when appropriate. (Grep the awful library for "emit_signal" to see this in action.)

You can create your own custom signals, and tell your own objects when to emit them. But most of the time we'll want to be binding handlers to the signals already being emitted by the awesome core. I haven't found much documentation yet about which signals are used by the core, and what arguments their handlers get passed. There are several requests on the mailing list for a comprehensive list of these.

So I grepped through the C code and the awful library (awesome-git, post-3.4.3), and compiled this draft. The "/1" at the end of a signal name indicates that when the signal is emitted its handlers get passed one argument. Those annotations are sometimes speculative; I didn't painstakingly inspect every relevant part of the code. I was aiming more to get a general overview, that we can refine over time.

Please help update this list when you see something is missing or erroneous. Please also help add brief explanations of when the various signals are emitted.

Each signal, connected with any kind of object (like button, client, etc.) carry additional (first on parameter list) argument, object-originator instance (please correct me if im wrong).

awesome
Signals emitted on the global  object:

button
Signals emitted on mouse  binding objects:

client
Signals emitted on  objects:

dbus
Signals emitted on  objects:

key
Signals emitted on  binding objects:

menu
Signals emitted on  objects:

screen
Signals emitted on  objects:

tag
Signals emitted on  objects:

timer
Signals emitted on  objects:

tooltip
Signals emitted on :

wibox
Signals emitted on  objects:

widget
Signals emitted on  objects:

"early" manage
By default there is a handler on "manage" signal - awful.rules.apply(c). And this handler sticks the client with current tag. One may want to perform some actions on client before this handler is run. Here is one possible solution of this problem - it adds an "early_manage" signal that is emitted when a new client is managed before awful.rules.apply(c) is run. Basically it is the same signal as manage, but its handlers are ran before "manage" signal handlers. Source: https://github.com/dobrover/myawesome/blob/master/awesome/utils/early_manage.lua

local early_manage = {} -- Module that adds "early_manage" signal that is executed -- before default awesome "manage" signal handler (which is awful.rules.apply) -- Usage: put require('early_manage').setup at the top of rc.lua -- And then just use "early_manage" signal as normal "manage". local capi = { client = client, } local awful = require 'awful' function early_manage.on_before_manage(...) -- Relies on the fact that emit_signal simply calls every signal handler -- in the current event handler. capi.client.emit_signal("early_manage", ...) end function early_manage.setup if not early_manage._setup then early_manage._setup = true capi.client.add_signal("early_manage") capi.client.disconnect_signal("manage", awful.rules.apply) capi.client.connect_signal("manage", early_manage.on_before_manage) capi.client.connect_signal("manage", awful.rules.apply) end end return early_manage