When

This document describes the new version of When, a Python-based automation tool for the desktop. This version, instead of incorporating the scheduler, relies on the whenever automation tool, which focuses on reliability and lightweightness, while trying to achieve a good performance even when running at low priority. In this sense, When acts as a wrapper for whenever, both providing a simple interface for configuration and an easy way to control the scheduler via an icon sitting in the tray area of your desktop. This version of When aims at being cross-platform, dynamically providing access to the features of whenever that are supported on the host environment.

This is still in its early development stage and still contains a lot of bugs and errors, yet it is capable of running whenever in the background and to control it via an icon in the system tray, create and edit the configuration file, capture the log and display a history window. All of this trying to mimic the behaviour of the old When tool, only available on Ubuntu distributions and restricted to the 16.XX and 18.XX editions, which is entirely Python based and is now abandoned because of the difficulty of adapting all needed DBus signals and checks to the ever-changing interface of the various Linux distributions.

Most of the interface of this release of When tries to be similar to the old version, although the need for cross-platform components pushes towards the adoption of the most widespread GUI library for Python, that is tkinter. Also, some of the extra features that are built into whenever call for a somewhat less-streamlined interface especially in terms of form layout.

The documentation is still underway, and the features are reduced compared to recent releases of the old version of When. However the structure of this new version is modular, and the design of whenever allows for the maximum flexibility in term of definitions of tasks, conditions, and events, so that new types of usable events can be defined along with the forms to edit them easily and write a well-formed configuration file.

For the moment this version of When is mostly intended as a proof-of-concept, even though it has reached a status in which all the basic features are implemented. The application may show problems due to lack of targeted exception handling, and genericity of checks on correctness of values provided via the UI. The UI itself still might have some quirks: the semantic of common gestures such as double clicks is not always respected, and some usual interface elements (pop-up boxes, buttons, and so on) might still result incomplete and not entirely consistent.

Usage

This version of When uses poetry: after running poetry install in the project directory to install all necessary Python dependencies, When can be launched as follows:

poetry run when COMMAND [OPTIONS]

where COMMAND is one of the following:

• config to launch the configuration utility, without staying resident (i.e. no system tray icon)
• start to launch the resident whenever wrapper displaying the control icon on the system tray area (non working on Linux: see #113)
• version to display version information.

More commands might be supported in the future. OPTIONS are the possible options, some of which are command specific.

• -D/--dir-appdata PATH: specify the application data and configuration directory (default: %APPDATA%\Whenever on Windows, ~/.whenever on Linux)
• -W/--whenever PATH: specify the path to the whenever executable (defaults to the one found in the PATH if any, otherwise exit with error)
• -L/--log-level LEVEL: specify the log level, all whenever levels are supported (default: info, specific to start)
• -h/--help: print help for the specific command

For the moment, due to the lack of access to some of the Python modules necessary for pystray to work correctly, running the resident whenever wrapper is not possible on Linux. However poetry run when config can be used to create and edit a whenever configuration file, and whenever_tray is available as a consistent wrapper.

NOTE: When can be run in debug mode, that is, it will not catch exceptions, and will use a DEBUG suffix for the application data directory: it also displays a color scheme that is neither dark nor light to underline its particular state. This behaviour can be enabled by setting 'DEBUG': True in the instantiation of AppConfig in lib/repocfg.py, instead of the current True value. This is useful when testing the application when an existing instance of whenever is running in production mode, possibly using the whenever_tray utility that normally shares the application data directory with When (starting with release 0.1.6). Note that a debug version of whenever should be used when a release version is running, because a debug version will not complain and refuse to start in case a non-debug version of the scheduler is already running. The full path to the desired whenever executable can be provided on the command line using the -W option.

When will be able to act as a wrapper only if a working and recent (not below 0.1.23) version of whenever is available, either in the system PATH or specified via the command line interface by using the -W switch.

Roadmap

The first goal is to obtain a fully functional version of this When edition, although supporting a minimal set of configuration items -- the ones that were supported at the time of the first launch of the old application. In this first stage of development, the effort will be devoted to amend bugs, enforce checks, handle possible exceptions that might occur in secondary threads and which may cause the application to become unstable, and more in general to make the application consistent in terms of both the user interface and the handling of the whenever subprocess, without adding new features. Once the minimal When application has reached an almost stable condition, new features (such as specific items and the tool box mentioned below) will be added.

Expectations and fulfillments for this version of When follow:

Editors

Editor forms for the items supported by whenever: should behave in a way similar to how the original When used to handle these items. Moreover, a main form is provided to access global configuration parameters and to create new items and edit or delete existing ones.

• Main Form
• Task: Command
• Task: Lua Script
• Condition: Interval
• Condition: Idle Session
• Condition: Time
• Condition: Command
• Condition: Lua Script
• Condition: Event (aka Bucket)
• Condition: DBus Method call (was not available in the original edition: form implemented but not made available)
• Event: Filesystem Monitoring
• Event: Command Line (not useful from a user POV: form implemented but not made available)
• Event: DBus Signal (was barely usable and restricted in the original edition: form implemented but not made available)

Specific command/Lua based tasks, command/Lua/DBus based conditions, DBus based events should be supported to mimic the old When behaviour:

• Task: Shut down the system
• Task: Lock the system
• Condition: Startup and Shutdown
• Condition: Suspend and Resume
• Condition: Session Lock and Unlock
• Condition: Screensaver
• Condition: Storage Device Connect and Disconnect
• Condition: Join or Leave a Network
• Condition: Battery is Charging, Discharging or Low
• Condition: System Load is Below a Certain Treshold

Other forms

The following forms, not related to the configuration application, are or should be only available from menus on the system tray:

• History Box
• Tool Box: configure/unconfigure startup link (also for whenever_tray), config file conversion tool (old When --> new When)

UI wrapper for the whenever scheduler

The following actions should be supported by a resident part of the application that only shows an icon in the tray area, and allows to choose entries from a popup menu.

• Show an About Box (to be improved)
• Show the task history, including execution time and outcome
• Suspend and resume conditions
• Reset conditions
• Pause and resume the scheduler
• Restart the scheduler
• Load the configuration utility (to be improved)

Other features that might be useful:

• Preserve paused state
• Log rotation and max number of old logs
• Reset conditions on wakeups from suspension or hibernation

The resident part of the application should not load the configuration utility at startup: it should only be loaded when the appropriate menu entry is selected, and all the modules should be removed from memory after the configuration utility has been left by the user.

Compatibility

When has been successfully tested on Windows (10 and 11) and Linux (Debian 12). On Debian 12, however, it does not run OOTB: some additional packages are needed, as it does not ship with tkinter support by default, nor it supports the AppIndicator protocol in a Gnome session. Thus both python3-tk and gir1.2-ayatanaappindicator3 need to be installed using the apt package manager. Moreover, on Wayland sessions the UI appears mangled and the graphic elements are actually unusable: it looks like tkinter only works well in Xorg sessions. Since Gnome does not support indicator icons direcltly, a Gnome shell extension capable of implementing this protocol has to be installed, such as AppIndicator and KStatusNotifierItem Support.

Before starting When on Debian 12, and before the poetry install step described above, the following option needs to be set in order to let the Python virtual environment access all the needed system modules:

poetry config virtualenvs.options.system-site-packages false

otherwise Python would not reach the modules needed to display the system tray icon and menu.

Research is underway on the possibility to provide When in "binary-ish" form too: there are some available tools that use the dependency management features in poetry to build packages suitable for various operating systems and their distributions.

Credits

The clock icon used for the application logo has been created by Rafi and is available at GraphicsFuel. All other icons have been found on Icons8:

• Alarm Clock
• Exclamation Mark
• Question Mark
• Settings Gear
• OK (Check Mark) Button
• Cancel Button
• Close Window
• Save
• Enter
• Add
• Remove
• Error
• New Document
• Pencil Drawing
• Delete
• File
• Folder

This utility uses the beautiful ttkbootstrap theme extension for tkinter, which provides a modern look consistent on all supported platform (and which is probably more clean and clear than it used to be in the GTK days). Also, chlorophyll is used to display and edit code and structured text, providing a more pleasant and up to date UI, and pystray to implement the system tray interface.