A simple, fast, and configurable pomodoro timer with multiple interfaces
This interface is displayed with ANSI terminal escape codes. It is the most lightweight interface, but it lacks several features, including:
- colors
- pausing
- skipping sections
This interface is displayed with the POSIX library ncurses. It is fully featured!
This interface is displayed with the cross-platform GUI library wxWidgets. It’s in early development and doesn’t support all pomocom settings yet.
pomocom has the following dependencies:
- C++20
- libncursesw v6.3+ (optional)
- wxWidgets v3.2+ (optional)
pomocom can be compiled using the Makefile by running make in the project’s root directory. To customize the compilation process, you may edit config.mk.
To install, run make install. This will copy the config directory in the project’s root directory to ~/.config/pomocom on POSIX systems.
To install just the pomocom binary and leave config directories untouched, run make installbin.
To uninstall, run make uninstall. This will remove the config directory at ~/.config/pomocom.
pomocom is configured with files found in ~/.config/pomocom. In there, pomocom.conf contains program settings values, and pomo files (ending in .pomo) contain timing section information.
pomocom.conf is written in the following format:
setting_name_1 setting_value_1
setting_name_2 setting_value_2
setting_name_3 setting_value_3
...Settings come in two distinct types: strings and numbers.
String settings can hold strings with spaces in them, but these spaces must come after the space character after the setting name.
Number settings can be split into multiple subtypes with different byte sizes: bool (1 byte), char (1 byte), int (1 byte), short (2 bytes), and long (8 bytes). These settings can also be set to string values that pomocom converts into numbers using an internal table of keywords (ex. you can set the setting interface to ncurses because ncurses is defined as a keyword that translates to the number 1). See the end of this section for a table of all keywords.
Here is an example pomocom.conf file:
interface ncurses
update_interval 1
pause_before_section_start true
breaks_until_long_reset 2
key.quit q
key.pause j
key.section_begin j
key.section_skip k
ncurses.color.pomocom.fg blue
ncurses.color.pomocom.bg default
ncurses.color.section_work.fg yellow
ncurses.color.section_work.bg default
ncurses.color.section_break.fg green
ncurses.color.section_break.bg default
ncurses.color.time.fg default
ncurses.color.time.bg defaultYou may also configure settings using command line arguments that follow the format --setting_name=setting_value. Settings specified in this way are set after pomocom.conf is read.
Here is a table of all settings:
| Name | Type | Default Value | Description |
|---|---|---|---|
| interface | int | ncurses | The type of interface pomocom will present |
| update_interval | long | 1 | The # of seconds to wait between screen updates |
| pause_before_section_start | bool | false | If true, makes pomocom pause before a section starts |
| set_terminal_title | bool | true | If true, sets the terminal title to “pomocom - (pomo file name)” on startup |
| set_terminal_title_countdown | bool | true | If true, sets the terminal title to a countdown (runs every screen update) |
| breaks_until_long_break | int | 2 | Controls how many break sections must pass before a long break occurs |
| key.quit | char | q | Key to quit pomocom |
| key.pause | char | j | Key to pause and unpause |
| key.section_begin | char | j | Key to begin the section |
| key.section_skip | char | k | Key to skip to the next section |
| path.config | string | ~/.config/pomocom/ | Path (ending with /) to the directory where pomocom.conf resides |
| path.section | string | ~/.config/pomocom/ | Path (ending with /) to the directory where pomo files reside |
| path.bin | string | ~/.config/pomocom/ | Path (ending with /) to the directory where executable scripts reside |
| ncurses.color.pomocom.fg | short | blue | Foreground color for the first line of text in the ncurses interface |
| ncurses.color.pomocom.bg | short | default | Background color for the first line of text in the ncurses interface |
| ncurses.color.section_work.fg | short | yellow | Foreground color for the work section name |
| ncurses.color.section_work.bg | short | default | Background color for the work section name |
| ncurses.color.section_break.fg | short | green | Foreground color for the break section names |
| ncurses.color.section_break.bg | short | default | Background color for the break section names |
| ncurses.color.time.fg | short | default | Foreground color for the time remaining in a section |
| ncurses.color.time.bg | short | default | Background color for the time remaining in a section |
Below is a table of all keywords. You can also see the initializers for keywords in src/settings.cc.
| Keyword | Intended For | Value in Source Code | Literal Value |
|---|---|---|---|
| true | booleans | 1 | 1 |
| false | booleans | 0 | 0 |
| ansi | interface | INTERFACE_ANSI | 0 |
| ncurses | interface | INTERFACE_NCURSES | 1 |
| wx | interface | INTERFACE_WX | 2 |
| default | ncurses colors | -1 | -1 |
| black | ncurses colors | COLOR_BLACK | ? |
| red | ncurses colors | COLOR_RED | ? |
| green | ncurses colors | COLOR_GREEN | ? |
| yellow | ncurses colors | COLOR_YELLOW | ? |
| blue | ncurses colors | COLOR_BLUE | ? |
| magenta | ncurses colors | COLOR_MAGENTA | ? |
| cyan | ncurses colors | COLOR_CYAN | ? |
| white | ncurses colors | COLOR_WHITE | ? |
Pomo files are written in the following format:
(name of work section)
(optional +)(command to run when the section is over)
(section duration in minutes)m(section duration in seconds)s
(name of break section)
(optional +)(command to run when the section is over)
(section duration in minutes)m(section duration in seconds)s
(name of long break section)
(optional +)(command to run when the section is over)
(section duration in minutes)m(section duration in seconds)s
If the section command is prefixed with +, the command will be prefixed with the path contained in the setting paths.bin (set by default to ~/.config/pomocom/). This is used so that you can easily execute files in a directory meant for pomocom scripts without needing to add this directory to your $PATH.
Here is an example pomo file:
work time
+msg.sh snare "work time"
25m0s
break time
+msg.sh square "break time"
5m0s
long break time
+msg.sh square "break time"
15m0s
Any argument that doesn’t start with - is interpreted as the pomo file to read. The path of this file will be the said argument prefixed with the setting paths.section (set by default to ~/.config/pomocom/) and suffixed with .pomo. If this argument starts with ./, the pomo file will be searched for relative to the working directory.
When pomocom is run with no specified pomo file, the pomo file standard.pomo in the program’s config directory is read.
-b
This will start the pomodoro timer on a short break section.
-B
This will start the pomodoro timer on a long break section.
-q (minutes of work section ) (minutes of break section) (minutes of long break section)
This stands for quick pomo file setup. It will make pomocom read the default pomo file and overwrite the lengths of each section with those specified.
To change settings, pass an argument starting with -- and ending with the setting name. The next argument should be the value of the setting.
Settings specified in this way will override the settings in pomocom.conf.
This will open the pomo file work.pomo in the directory contained in the setting paths.section and set the setting interface to wx, regardless of what interface is set as in pomocom.conf.
pomocom work --interface wxThis will open the pomo file abc.pomo in the working directory that the command is run from.
pomocom ./abcThese are not available in the ANSI interface.
- j
- Begin the timing section, pause, and unpause
- k
- Skip the section
- q
- Quit