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:

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

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 awesome object:

button

Signals emitted on mouse button binding objects:

client

Signals emitted on client objects:

dbus

Signals emitted on dbus objects:

	{
			type: [signal,method_call,method_return,error,unknown] -- one of those options
			interface: ...
			path: ...
			member: ...
			bus: [system,session] -- one of those options
	}

key

Signals emitted on key binding objects:

menu

Signals emitted on menu objects:

screen

Signals emitted on screen objects:

tag

Signals emitted on tag objects:

timer

Signals emitted on timer objects:

tooltip

Signals emitted on tooltip:

wibox

Signals emitted on wibox objects:

widget

Signals emitted on widget objects: