Event listeners¶
What are event listeners?¶
Event listeners
provide you with the ability to keep track of certain events, and change module behaviour accordingly. A short summation of event listeners:
- Event listeners are specified on a per-module-basis.
- There are different
types
of event listeners.- Event listeners determine exactly when the actions you specify within a module’s on_event action block are executed.
- Event listeners are optional, you can write valid modules without specifying one. Actions specified within the
on_event
action block will never be executed when no module event listener is specified.- Event listeners provide the module with the
{event}
placeholder when specifyingactions
. It is replaced by the currentevent
at runtime. The replacement value is specific for that specific event listener’s type, and dynamically changes according to rules set by the event listener.
What are event listeners used for?¶
Event listeners provide you with the tools needed for dynamic module behaviour. Sometimes you want a module to execute different shell commands, and/or compile templates with different context values, depending on exactly when those actions are performed.
How to set a module event listener¶
Module event listeners are defined within the module block it is supposed to provide functionality for. The syntax is as follows:
some_dynamic_module:
event_listener:
type: type_of_event_listener
option1: whatever
option2: something
...
Most event listeners provide you with additional options in order to tweak their behaviour. These are specified at the same indentation level as the event listener type.
Events¶
Module event listeners keep track of some type of event
and trigger the on_event
action block whenever it detects a new event. You can refer to the current event in your module actions with the {event}
placeholder.
Caution
When you use placeholders, you must take care that the placeholder is not interpreted as a YAML dictionary instead of a string. The following will not work as intended:
some_option: {event}
This is interpreted as the dictionary {'event': None}
. In this case you must mark the option explicitly as a string:
some_option: '{event}'
Using quotes is not necessary when the placeholder is part of a greater string. This works:
some_option: echo {event}
An example using events¶
The use of events
in modules is best explained with an example. Please take a look at this example using the weekday
event listener in order to set a separate desktop wallpaper for each day of the week.
Event listener types¶
Here is a list of all available Astrality module event listeners and their configuration options. If what you need is not available, feel free to open an issue with a event listener request!
Daylight¶
- Description
- Keeps track of the daylight at a specific location, i.e. if the sun is above the horizon or not.
- Specifier
type: daylight
- Events
day
,night
Option | Default | Description |
---|---|---|
latitude | 0 | Latitude coordinate point of your location. |
longitude | 0 | Longitude coordinate point of your location. |
elevation | 0 | Height above sea level at your location. |
These coordinates can be obtained from this website.
Example configuration
daylight_module:
event_listener:
type: daylight
latitude: 63.446827
longitude: 10.421906
Solar¶
- Description
- Keeps track of the sun’s position in the sky at a given location.
- Specifier
type: solar
- Events
sunrise
,morning
,afternoon
,sunset
,night
Option | Default | Description |
---|---|---|
latitude | 0 | Latitude coordinate point of your location. |
longitude | 0 | Longitude coordinate point of your location. |
elevation | 0 | Height above sea level at your location. |
These coordinates can be obtained from this website.
Example configuration
solar_module:
event_listener:
type: solar
latitude: 63.446827
longitude: 10.421906
Static¶
- Description
- An event listener which never changes its event. This is the default event listener for modules.
- Specifier
type: static
- Events
static
No configuration options are available for the static event listener.
Example configuration
static_module:
...
Time of day¶
- Description
- Keeps track of a specific time interval for each day of the week. Useful for tracking when you are at work.
- Specifier
type: time_of_day
- Events
on
,off
Option | Default | Description |
---|---|---|
monday | '09:00-17:00' |
The time of day that is considered ‘on’. |
tuesday | '09:00-17:00' |
The time of day that is considered ‘on’. |
wednesday | '09:00-17:00' |
The time of day that is considered ‘on’. |
thursday | '09:00-17:00' |
The time of day that is considered ‘on’. |
friday | '09:00-17:00' |
The time of day that is considered ‘on’. |
saturday | '' |
The time of day that is considered ‘on’. |
sunday | '' |
The time of day that is considered ‘on’. |
Example configuration
european_tue_to_sat_work_week:
event_listener:
type: time_of_day
monday: ''
tuesday: '08:00-16:00'
wednesday: '08:00-16:00'
thursday: '08:00-16:00'
friday: '08:00-16:00'
saturday: '08:00-16:00'
Weekday¶
- Description
- Keeps track of the weekdays.
- Specifier
type: weekday
- Events
monday
,tuesday
,wednesday
,thursday
,friday
,saturday
,sunday
No configuration options are available for the weekday event listener.
Example configuration
weekday_module:
event_listener:
type: weekday
Periodic¶
- Description
- Keeps track of constant length time intervals.
- Specifier
type: periodic
- Events
0
,1
,2
,3
, and so on…
Option | Default | Description |
---|---|---|
seconds | 0 | Number of seconds between each period. |
minutes | 0 | Number of minutes between each period. |
hours | 0 | Number of hours between each period. |
days | 0 | Number of days between each period. |
If the configured time interval is of zero length, Astrality uses hours: 1
instead.
Example configuration
periodic_module:
event_listener:
type: periodic
hours: 8