Signals

From awesome
Jump to: navigation, search

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[edit]

Signals emitted on the global awesome object:

Name When emitted Arguments
exit Just before awesome exits Boolean value indicating if awesome is restarting or not
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


button[edit]

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

client[edit]

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 when a client gains focus the client object
unfocus when a client looses focus the client object
tagged when client is tagged new tag
untagged when client looses tag deleted tag
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

dbus[edit]

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.

key[edit]

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

menu[edit]

Signals emitted on menu objects:

Name When emitted Arguments
mouse::enter none
mouse::leave none

screen[edit]

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

tag[edit]

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. the tag object
property::filtered When property changes. unknown
property::hide When property changes. unknown
property::icon When property changes. unknown
property::layout when the layout of a tag changes the tag object
property::mwfact When property changes. the tag object
property::ncol When property changes. the tag object
property::nmaster When property changes. the tag object
property::windowfact When property changes.

timer[edit]

Signals emitted on timer objects:

Name When emitted Arguments
timeout none
property::timeout When property changes. none

tooltip[edit]

Signals emitted on tooltip:

Name When emitted Arguments
mouse::enter none
mouse::leave none

wibox[edit]

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

widget[edit]

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

"early" manage[edit]

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