utilities/kclock/README.md

0001 <!--
0002 - Copyright 2020 Han Young <hanyoung@protonmail.com>
0003 - Copyright 2020 Devin Lin <espidev@gmail.com>
0004 - SPDX-License-Identifier: GPL-2.0-or-later
0005 -->
0006
0007 # KClock <img src="logo.png" width="40"/>
0008 A convergent clock application for Plasma.
0009
0010 <a href='https://flathub.org/apps/details/org.kde.kclock'><img width='190px' alt='Download on Flathub' src='https://flathub.org/assets/badges/flathub-badge-i-en.png'/></a>
0011
0012 ## Features
0013 * Alarms
0014 * Stopwatch
0015 * World Clocks
0016 * Timers
0017
0018 ## Links
0019 * Project page: https://invent.kde.org/plasma-mobile/kclock
0020 * File issues: https://bugs.kde.org/describecomponents.cgi?product=KClock
0021 * Development channel: https://matrix.to/#/#plasmamobile:matrix.org
0022
0023 ## Installing
0024 This will compile and install kclock, kclockd, and the plasmoids onto the system. When running kclock, make sure that kclockd is running first (it is configured to autostart in sessions).
0025
0026 ```
0027 mkdir build
0028 cd build
0029 cmake .. # add -DCMAKE_BUILD_TYPE=Release to compile for release
0030 make
0031 sudo make install
0032 ```
0033
0034 ## Components
0035 KClock is split into three components: **kclock** (front-end), **kclockd** (backend-daemon), and **plasmoids**.
0036
0037 ### `kclockd`
0038 The background daemon, which is configured to autostart. It has the following responsibilities:
0039 * Schedule wakeups with [PowerDevil](https://invent.kde.org/plasma/powerdevil), which handles waking from suspend for alarms and timers.
0040 * Exposing alarms, timers, and settings models via a D-Bus interface.
0041 * Alarm/Timer notifications and ringing audio.
0042 * Indicator on system tray for pending alarms.
0043
0044 `kclockd` exposes its API in D-Bus under the service name `org.kde.kclockd`. Front-end applications like `kclock` and its plasmoids completely depend on it for clock functionality, which allows alarms and timers to function in the background when the front-end applications are not running.
0045
0046 If PowerDevil is detected, it will use PowerDevil's scheduleWakeup feature to wakeup for alarm notifications.
0047
0048 If you want to disable this behaviour, pass the `--no-powerdevil` option when launching kclockd. Note that while running in `--no-powerdevil` mode, kclockd will fail to keep track of time if the system sleeps, which is quite common for mobile devices.
0049
0050 `kclockd` will automatically start up in `--no-powerdevil` mode and not have suspend waking functionality if:
0051 * PowerDevil is not running (ex. on GNOME, Phosh, etc.)
0052 * On BSD system
0053
0054 #### `kclockd` D-Bus interface
0055 After installing, five D-Bus interface XML files are copied to the KDE D-Bus interface directory.
0056
0057 These are:
0058 * org.kde.kclockd.KClockSettings.xml
0059 * org.kde.kclockd.Alarm.xml
0060 * org.kde.kclockd.AlarmModel.xml
0061 * org.kde.kclockd.TimerModel.xml
0062 * org.kde.kclockd.Timer.xml
0063
0064 These files can be used to generate the D-Bus adaptor. Alarm and Timer will be registered under path "/Alarms/" or "/Timers/" + its uuid's Id128 string representation (ex. *8c7d59b3befa49a48853959fe7e025d7*). However, the "remove" slots in AlarmModel or TimerModel only accept its normal representation, (ex. *{8c7d59b3-befa-49a4-8853-959fe7e025d7}*). One can get the normal string by calling the getUUID() method in each alarm/timer. Timer is in seconds precision, but you may want to call elapsed() method every 500ms or so to avoid going out of sync with kclockd.
0065
0066 ### `kclock`
0067 A front end for kclockd written in Kirigami for Plasma Mobile and the desktop.
0068
0069 Run with these environment variables to have mobile controls:
0070 ```
0071 QT_QUICK_CONTROLS_MOBILE=true kclock
0072 ```
0073
0074 ### Plasmoids
0075 Various plasmoids for kclockd exist, and some also communicate with [KWeather](https://invent.kde.org/plasma-mobile/kweather).
0076
0077 Currently we have two plasmoids, expect more in the future.
0078
0079 Intended to provide `widgets` similar to those you can find on mainstream mobile platforms.
0080
0081 ## Gallery
0082
0083 <img src="screenshots/kclock-mobile-timezones.png" width="200px">
0084 <img src="screenshots/kclock-mobile-timers.png" width="200px">
0085 <img src="screenshots/kclock-mobile-stopwatch.png" width="200px">
0086 <img src="screenshots/kclock-mobile-alarms.png" width="200px">
0087 <img src="screenshots/kclock-desktop-timezones.png" width="400px">
0088 <img src="screenshots/kclock-desktop-timer.png" width="400px">