Rclock is a highly customizable digital clock for terminal interfaces written in C that runs on POSIX platforms, the included features of the Rclock are the possibility of change the color of the components, optionally hide the date and the seconds, set a custom date and so on...
- Set a color to the clock
- Set a color to the date
- Set a color for each digit individually
- Set a color to the clock colons
- Set a color only for the digits
- Use a custom date format
- Set a custom hour
- Set a custom minute
- Set a custom second
- Set a custom time using the format xx:xx:xx
- Set a custom day
- Set a custom month
- Set a custom year
- Set a custom date using the format DD/MM/YYYY
- Hide the seconds
- Hide the date
- Pomodoro mode
Running the program for the first time
Configuring a new color to the clock
This software is built using the following technologies:
- C programming language
- Meson build system
- Ncurses library
- Anemone library
Tests performed on this software:
- Unit testing
- Integration testing
Here is all you need to know to install and run the Rclock.
The compiler used for developing the Rclock was the GCC 13.2.1. Using the same compiler and the same/newer versions is advisable.
The Meson build system documentation can be found on this link: https://mesonbuild.com/Getting-meson.html
The Rclock uses the Ncurses library to create and manipulate components on screen. This library is part of POSIX, a Linux system typically has this library by default.
The Anemone is a library used for command-line argument parsing. This library is defined as a submodule of this repository, so you don't need to worry about downloading it manually, however, a couple of commands will be necessary to pull and compile the source code.
The source code of this repository can be downloaded with the following git command:
git clone --recursive https://github.com/Romulo-Moraes/Rclock.gitThe --recursive flag is used for downloading the submodules beyond the repository source code itself.
The Anemone repository provides its own script for building the library, it's located on the root of the project. So to build the Anemone we need to run the following commands with the premise that you are currently at the root of the Rclock repository:
cd ./lib/Anemone
sh ./make_lib.sh
cd ../../Once back to the Rclock root, we need to setup the Meson build system for compiling the repository. Running these commands should accomplish this task:
meson setup build
cd buildAfter configuring Meson, you have two options for building the application.
This option just compiles the project and creates the executable in the current directory.
meson compileThis option compiles and also installs the executable globally on your machine.
sudo meson installOnce successfully installed, the Rclock executable is globally accessible on your system and can be run. To launch the application, simply type the following command in the terminal:
rclockAfter running this command, the digital clock should be visible on screen with the default configurations.
Press Enter if you want to close the application.
One of the most attractive features of the Rclock is the ability of set new colors for each component, there is a variety of command-line flags that can define new colors for each piece of the clock.
The Rclock has a set of built-in colors that are available to be used in any Rclock component.
- black
- red
- green
- yellow
- blue
- magenta
- white
The Rclock is divided into components, this approach makes the development easier and increase the ways of customizations.
- Digits (Individually)
- Colons
- Date
This flag changes the color of all digits and all colons of the clock.
--clock-color or -c <color>--date-color or -d <color>You can change the color of the digits individually by passing the flag --color with a roman number between 1 (I) and 6 (VI), or its corresponding short version.
--color-I or -q <color>
--color-II or -Q <color>
--color-III or -P <color>
--color-IV or -p <color>
--color-V or -K <color>
--color-VI or -k <color>--colon-color or -o <color>--digits-color or -l <color>It is possible to set a custom date to the Rclock, either individually or using a date format.
--custom-day or -D <month-day>--custom-month or -O <1-12>--custom-year or -Y <positive value>The following flag sets a new day, month and year using a date format.
--custom-date or -D <DD/MM/YYYY>By default, the date is displayed using a built-in format. However, you can specify a custom date format, and Rclock will use it instead of the default format.
--date-format or -f <strftime format>This feature uses the replacement strategy of the strftime C function, so here is the cheatsheet to help you design your own format:
| Specifier | Replaced By | Example |
|---|---|---|
| %a | Abbreviated weekday name | Sun |
| %A | Full weekday name | Sunday |
| %b | Abbreviated month name | Mar |
| %B | Full month name | March |
| %c | Date and time representation | Sun Aug 19 02:56:02 2012 |
| %d | Day of the month (01-31) | 19 |
| %H | Hour in 24h format (00-23) | 14 |
| %I | Hour in 12h format (01-12) | 05 |
| %j | Day of the year (001-366) | 231 |
| %m | Month as a decimal number (01-12) | 08 |
| %M | Minute (00-59) | 55 |
| %p | AM or PM designation | PM |
| %S | Second (00-61) | 02 |
| %U | Week number with the first Sunday as the first day of week one (00-53) | 33 |
| %w | Weekday as a decimal number with Sunday as 0 (0-6) | 4 |
| %W | Week number with the first Monday as the first day of week one (00-53) | 34 |
| %x | Date representation | 08/19/12 |
| %X | Time representation | 02:50:06 |
| %y | Year, last two digits (00-99) | 01 |
| %Y | Year | 2012 |
| %Z | Timezone name or abbreviation | CDT |
| %% | A % sign | % |
This is the default format used by the project:
"%A, %b %d %Y"It is also possible to set a custom time to the Rclock, either individually or using a time format.
--custom-hour or -H <0-23>--custom-minute or -M <0-59>--custom-second or -S <0-59>This flag sets a new hour, minute and second using a time format.
--custom-time or -T <XX:XX:XX>The Rclock can hide a group of components to make itself smaller, useful for limited space or personal taste.
--hide-date or -h--hide-seconds or -iRclock is designed to automatically hide the date and seconds when needed. If the terminal becomes too small to render the clock properly, the seconds will be hidden to save horizontal space, and the date will be hidden to save vertical space.
In the newer versions of the Rclock, the Pomodoro mode was implemented and can now be easily accessed through a new optional flag.
The Pomodoro mode is a implementation of the Pomodoro Technique, that is a time management method that breaks work into intervals of 25 minutes, separated by short breaks. Each interval is known as a Pomodoro, and each short break is known as a Rest time on Rclock.
By default, the rest time is 5 minutes. However, after completing three pomodoro sessions, you'll receive a 15-minute rest before the cycle restarts.
To launch the Rclock on Pomodoro mode, you must pass the flag --pomodoro to the program. This command will make the clock show up, ready to start a new pomodoro.
When the clock hits 00:00 in either the pomodoro or rest time, the terminal screen will start flashing alternately in red and transparent. Additionally, a push notification will appear on your desktop every 20 seconds until you turn off the alarm.
Pomodoro mode introduces new color customization options. Use the following flag to change the text color displayed above and below the clock:
--labels-color or -L <color>Unlike the normal clock mode, you can't exit the pomodoro session by simply pressing Enter once.
To prevent accidentally leaving the session while maintaining the practicality of a menuless design, you need to press Enter three times within 350 milliseconds. This will close the application and restore the terminal to its default configuration.
