eventd.conf(5)

Global configuration file

This file is passed to every plugin so they can read their global configuration too.

Sections read in these files are identified as “Global sections”.

Event files

Event files describes the events that the daemon will recognise when an event collection plugin will push it.

These files are only ever read by eventd itself.

They define a list of action ids that eventd (and its plugins) should trigger when a matching event fires up.

Unknown action ids are silently ignored. If an event ends with an empty action list, it is discarded.

Sections read in these files are identified as “Event sections”.

Action files

Action files describes the actions that the plugins may do when dispatching an event. Each action can itself trigger subactions.

eventd itself reads very little information in there, but plugins can read as much as they want to determine their exact behaviour when the action is triggered.

Official action plugins require at least their own configuration section to do something. They have no “catch-all” action.

Sections read in these files are identified as “Action sections”.

Enumeration

An enumeration is a string which can take a limited set of values. Values are case-insensitive.

Accepted values depend on the key and will be listed in the relevant key descriptions.

Format strings

A format string can contain references to event data.

References use a shell-like format: ${reference-name}. Each reference is resolved to a data that is substitued to the reference at the corresponding place in the string. The reference-name can be composed of alphabetic characters, dashes ('-') and underscores ('_').

You can use an array-like syntax for some values: ${reference-name[key]} (square brackets [] are literals here). The key can be a name or a number depending on the data pointed by reference-name. If key starts with a @, then the remaining is used as a join value. You can use fallback values, substitute values or regexes on array members. In case of joined values, such operations are done on the joined values as a whole.

You can use a fallback value if the data resolves to nothing or false. The syntax is: ${reference-name:-fallback-value}.

You can use a substitute value if (and only if) the data resolves to something or true. The syntax is: ${reference-name:+substitute-value}.

You can use a substitute value if (and only if) the data resolves to nothing or false. The syntax is: ${reference-name:!substitute-value}.

You can use a switch substitute if the data resolves to a boolean. The syntax is: ${reference-name:{separator value-if-false separator value-if-true}} (spaces added for readability only, they are not ignored when parsed).

You can use a range substitute if the data resolves to a number. The syntax is: ${reference-name:[separator range-start separator range-end [separator substitute-value…]]} (spaces added for readability only, they are not ignored when parsed, the external square brackets [] are literals here).

You can use a prettify flag to make a big value more readable. The syntax is: ${reference-name(flag[addition])}. The following flags are supported:

You can replace parts of the data using the regex mechanism. The syntax is: ${reference-name/regex/replacement}. The replacement part is optional (including the preceding forward slash). If it is omitted, matching parts of the data will simply be removed. You can repeat the /regex/replacement part to replace as many patterns as you like. Each pattern is matched against the previous replacement so be careful in your order.

Examples (with data and resolved string):

Please note that the config file format uses the backslash (\) for escaping sequences. Therefore, you will have to escape it if it is needed in your format string (e.g. to uses backreferences in the replacement part of the regex syntax).

File URI

A file URI is a string that can be either a data name or a format string of an URI scheme.

In the former case, the data is searched in the event, and then either parsed as an URI or used directly if it is a GVariant of type "(msmsay)" containing the MIME type, the charset, and the data.

Three URI schemes are supported: file:// theme: and data: (Base64 extension only, charset and mime type may be ignored).

A theme: URI is has the form theme:[theme-name/]item-name.

Colour strings

The colour string format is borrowed from the CSS4 Color values. Hexadecimal (#-prefixed), rgb() RGB(A), hsl() HSL(A), hwb() HWB and colour names notations are supported.

Here is a quick description:

Binding strings

The binding string format supports two (and a half) notations. It can be either Modifier-Modifier-Bind or the GTK+ accelerator format.

The bind can either be a keysym name, a keycode in square brackets (e.g. [10]) or a mouse button specification (e.g. MousePrimary or MouseDPrimary for double click).

Other types

More specific types are described in the relevant key description.

Section [Server]

Section [Relay]

Section [Relay name]

Section [File]

This section if for file inclusion. It allows a more customised management of your files.

Section [Event category [name [sub-name]]]

This is the main event configuration section. It contains the core related settings.

The category and name are used to match the event while sub-name is only meant to differentiate sections and is not used anywhere in eventd.

You can use * as the name name to have data matches on a whole category.

Section [Action]

This section allows to identify the action uniquely and link it to subactions if wanted.

Section [Flags]

This section allows to change the flags of the running eventd as an action. The flags are changed before any plugin actions configured on the same action, use subactions to order the flags changes differently.