Signals
From awesome
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.
Contents |
[edit] awesome
Signals emitted on the global awesome object:
| Name | When emitted | Arguments |
|---|---|---|
| exit | Just before awesome exits | |
| spawn::initiated | When a new client is beginning to start | Table which describes the spawn event |
| spawn::change | When one of the fields from the spawn::initiated table changes | Same as spawn::initiated |
| spawn::canceled | For some reason the application aborted startup | Table which only got the "id" key set |
| spawn::timeout | An application started a spawn event but didn't start in time. | Table which only got the "id" key set |
| spawn::completed | An application finished starting | Table which only got the "id" key set |
| debug::error | A call into the lua code aborted with an error | Lua error message |
| debug::deprecation | A deprecated lua function was called | The error message which also describes the new API to use |
| debug::index::miss | An invalid key was read from an object (e.g. c.foo) | The object and they key that was attempted to read |
| debug::newindex::miss | An invalid key was written to an object (e.g. c.foo = "bar") | The object, the key being written and the value written to that key |
[edit] button
Signals emitted on mouse button binding objects:
| Name | When emitted | Arguments |
|---|---|---|
| press | When bound mouse button + modifiers are pressed. | one or more args |
| release | When bound mouse button + modifiers are released. | one or more args |
| property::button | When property changes. | none |
| property::modifiers | When property changes. | none |
[edit] client
Signals emitted on client objects:
| Name | When emitted | Arguments |
|---|---|---|
| new | one arg | |
| manage | two args | |
| unmanage | one arg | |
| list | Before manage, after unmanage, and when clients swap. | none |
| focus | one arg | |
| unfocus | one arg | |
| tagged | one arg | |
| untagged | one arg | |
| marked | unknown | |
| unmarked | unknown | |
| property::above | When property changes. | none |
| property::below | When property changes. | none |
| property::border_color | When property changes. | none |
| property::border_width | When property changes. | none |
| property::class | When property changes. | none |
| property::floating | When property changes. | unknown |
| property::fullscreen | When property changes. | none |
| property::geometry | When height or width changes. | none |
| property::group_window | When property changes. | none |
| property::height | When property changes. | none |
| property::hidden | When property changes. | none |
| property::icon | When property changes. | none |
| property::icon_name | When property changes. | none |
| property::instance | When property changes. | none |
| property::machine | When property changes. | none |
| property::maximized_horizontal | When property changes. | none |
| property::maximized_vertical | When property changes. | none |
| property::minimized | When property changes. | none |
| property::modal | When property changes. | none |
| property::name | When property changes. | none |
| property::ontop | When property changes. | none |
| property::opacity | When property changes. | none |
| property::pid | When property changes. | none |
| property::role | When property changes. | none |
| property::screen | When property changes. | unknown |
| property::size_hints_honor | When property changes. | none |
| property::skip_taskbar | When property changes. | none |
| property::sticky | When property changes. | none |
| property::struts | When property changes. | none |
| property::transient_for | When property changes. | none |
| property::type | When property changes. | none |
| property::urgent | When property changes. | none |
| property::width | When property changes. | none |
| property::window | When property changes. | none |
| property::x | When property changes. | none |
| property::y | When property changes. | none |
| property::buttons | When property changes. | none |
| property::keys | When property changes. | none |
[edit] dbus
Signals emitted on dbus objects:
| Name | When emitted | Arguments |
| (interface name) | Table of this format:
{
type: [signal,method_call,method_return,error,unknown] -- one of those options
interface: ...
path: ...
member: ...
bus: [system,session] -- one of those options
}
Handler should return even number of values. |
[edit] key
Signals emitted on key binding objects:
| Name | When emitted | Arguments |
|---|---|---|
| press | one arg+ | |
| release | one arg+ | |
| property::modifiers | When property changes. | none |
| property::key | When property changes. | none |
[edit] menu
Signals emitted on menu objects:
| Name | When emitted | Arguments |
|---|---|---|
| mouse::enter | none | |
| mouse::leave | none |
[edit] screen
Signals emitted on screen objects:
| Name | When emitted | Arguments |
|---|---|---|
| padding (from awful.screen) | unknown | |
| arrange (from awful.layout) | unknown | |
| tag::attach | one arg | |
| tag::detach | one arg | |
| tag::history::update | unknown | |
| property::screen | When property changes. | unknown |
| property::workarea | When property changes. | none |
[edit] tag
Signals emitted on tag objects:
| Name | When emitted | Arguments |
|---|---|---|
| tagged | unknown | |
| property::name | When property changes. | none |
| property::screen | When property changes. | none |
| property::selected | When property changes. | none |
| unknown | ||
| property::filtered | When property changes. | unknown |
| property::hide | When property changes. | unknown |
| property::icon | When property changes. | unknown |
| property::layout | When property changes. | unknown |
| property::mwfact | When property changes. | unknown |
| property::ncol | When property changes. | unknown |
| property::nmaster | When property changes. | unknown |
| property::windowfact | When property changes. |
[edit] timer
Signals emitted on timer objects:
| Name | When emitted | Arguments |
|---|---|---|
| timeout | none | |
| property::timeout | When property changes. | none |
[edit] tooltip
Signals emitted on tooltip:
| Name | When emitted | Arguments |
|---|---|---|
| mouse::enter | none | |
| mouse::leave | none |
[edit] wibox
Signals emitted on wibox objects:
| Name | When emitted | Arguments |
|---|---|---|
| mouse::enter | none | |
| mouse::leave | none | |
| property::geometry | When height or width changes? (not sure if this signal is emitted) | unknown |
| property::bg | When property changes. | none |
| property::bg_image | When property changes. | none |
| property::border_color | When property changes. | none |
| property::border_width | When property changes. | none |
| property::buttons | When property changes. | none |
| property::cursor | When property changes. | none |
| property::fg | When property changes. | none |
| property::height | When property changes. | none |
| property::ontop | When property changes. | none |
| property::opacity | When property changes. | unknown |
| property::orientation | When property changes. | none |
| property::screen | When property changes. | none |
| property::shape_bounding | When property changes. | none |
| property::shape_clip | When property changes. | none |
| property::struts | When property changes. | none |
| property::visible | When property changes. | none |
| property::widgets | When property changes. | none |
| property::width | When property changes. | none |
| property::x | When property changes. | none |
| property::y | When property changes. | none |
[edit] widget
Signals emitted on widget objects:
| Name | When emitted | Arguments |
|---|---|---|
| press | one or more args | |
| release | one or more args | |
| mouse::enter | none | |
| mouse::leave | none | |
| property::buttons | When property changes. | none |
| property::type | When property changes. | none |
| property::visible | When property changes. | none |
