diff --git a/docs/README.md b/docs/README.md index 197a90c..85bee34 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,15 +1,9 @@ -# NAME - -*powerkit* - Desktop independent power manager for Linux - -# SYNOPSIS - -powerkit *`[--config]`* *`[--set-brightness-up]`* *`[--set-brightness-down]`* *`[--sleep]`* *`[--hibernate]`* *`[--lock]`* - -# DESCRIPTION +# powerkit Desktop independent power manager for use with alternative X11 desktop environments and window managers on Linux. +![Screenshot of the powerkit configuration](screenshot.png) + * Implements *``org.freedesktop.ScreenSaver``* service * Implements *``org.freedesktop.PowerManagement.Inhibit``* service * Automatic actions on lid, idle and low battery @@ -24,207 +18,4 @@ Desktop independent power manager for use with alternative X11 desktop environme * Screen backlight support * Notification support (can use *``org.freedesktop.Notifications``* if available) -# USAGE - -powerkit should be started during the X11 user session. Consult the documentation for your desktop environment or window manager for launching startup applications. - - * In *Fluxbox* add *``powerkit &``* to the *``~/.fluxbox/startup``* file - * In *Openbox* add *``powerkit &``* to the *``~/.config/openbox/autostart``* file. - -**Do use powerkit if your desktop environment or window manager already has a power manager or screen saver service running.** - -## CONFIGURATION - -Settings are available directly from the system tray icon or run *``powerkit --config``*. You should also be able to lauch the powerkit settings from your desktop application menu (if available). - -## SCREEN SAVER - -powerkit implements a basic screen saver to handle screen blanking, poweroff and locking feature. - -Locking feature depends on ``xsecurelock``. - -You can override the lock command with *``screensaver_lock_cmd=``* in *`~/.config/powerkit/powerkit.conf`*. Note that the command must not contain spaces. - -## BACKLIGHT - -The current display brightness (on laptops and supported displays) can be adjusted with the mouse wheel on the system tray icon or through the system tray menu. - -powerkit also supports the following commands that can be used for global shortcuts, scripts etc: - -*`powerkit --set-brightness-up`* -: Set default display brightness up. - -*`powerkit --set-brightness-down`* -: Set default display brightness down. - -On Fluxbox you can add the commands to the *`~/.fluxbox/keys`* file: - -``` -XF86MonBrightnessUp :Exec powerkit --set-brightness-up -XF86MonBrightnessDown :Exec powerkit --set-brightness-down -``` - -## HIBERNATE - -If hibernate works depends on your system, a swap partition (or file) is needed by the kernel to support hibernate. - -***Consult your system documentation regarding hibernation***. - -## ICONS - -powerkit will use the existing icon theme from the running desktop environment or window manager. - -You can override the icon theme in the *`~/.config/powerkit/powerkit.conf`* file, use *``icon_theme=``*. - -# FAQ - -## How does an application inhibit the screen saver? - -The preferred way to inhibit the screen saver from an application is to use the *org.freedesktop.ScreenSaver* specification. Any application that uses *org.freedesktop.ScreenSaver* will work with powerkit. - -Popular applications that uses this feature is Mozilla Firefox, Google Chrome, VideoLAN VLC and many more. - -## How does an application inhibit suspend actions? - -The preferred way to inhibit suspend actions from an application is to use the *org.freedesktop.PowerManagement* specification. Any application that uses *org.freedesktop.PowerManagement* will work with powerkit. - -Common use cases are audio playback, downloading, rendering and similar. - -## Google Chrome/Chromium does not inhibit the screen saver or power manager!? - -Chrome does not use *org.freedesktop.ScreenSaver* or *org.freedesktop.PowerManagement* until it detects a supported desktop environment. Add the following to *``~/.bashrc``* or the *``google-chrome``* launcher if you don't run a supported desktop environment: - -``` -export DESKTOP_SESSION=xfce -export XDG_CURRENT_DESKTOP=xfce -``` - -## Mozilla Firefox does not inhibit the power manager during audio playback and/or downloading!? - -This is an issue with Firefox (missing feature). Use a different browser or open a request on the Firefox issue tracker. - -Firefox should inhibit the power manager during audio playback (regardless of video) and during download (active queue). Currently Firefox only inhibit the screen saver during video playback. Chrome/Chromium does this correctly. - -# REQUIREMENTS - -powerkit requires the following dependencies: - - * *[X11](https://www.x.org)* - * *[libXss](https://www.x.org/archive//X11R7.7/doc/man/man3/Xss.3.xhtml)* - * *[libXrandr](https://www.x.org/wiki/libraries/libxrandr/)* - * *[Qt](https://qt.io)* 5.15 *(Core/DBus/Gui/Widgets)* - * *[logind](https://www.freedesktop.org/wiki/Software/systemd/logind/)* *(or compatible service)* - * *[UPower](https://upower.freedesktop.org/)* *(or compatible service)* - * *[xsecurelock](https://github.com/google/xsecurelock)* - -# BUILD - -First make sure you have the required dependencies installed, then review the most common build options: - - * *``CMAKE_INSTALL_PREFIX=``* - Install target. *``/usr``* recommended. - * *``CMAKE_BUILD_TYPE=``* - Build type. *``Release``* recommended - -Now configure powerkit with CMake and build: - -``` -mkdir build && cd build -cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release .. -make -j4 -``` - -All you need is the *``powerkit``* binary located in the build directory, you can run it from any location. - -## Install - -Use regular *``make install``* with optional *``DESTDIR``*: - -``` -make DESTDIR= install -``` - -or make a native package: - -``` -cpack -G DEB -``` -``` -cpack -G RPM -``` - -# CHANGELOG - -## 2.0.0 (TBA) - - * Recommended locker is ``xsecurelock`` - * Added support for "modern" logind - * Removed support for ConsoleKit - * Removed support for XScreenSaver - * Added basic screen saver - * Easier to use (minimal/no setup) - * New UI - * Major code changes - -# OPTIONS - -*``--config``* -: Launch configuration. - -*`--set-brightness-up`* -: Set default display brightness up. - -*`--set-brightness-down`* -: Set default display brightness down. - -*`--sleep`* -: Suspend computer now. Can be combined with *`--hibernate`* for suspend then hibernate after X amount of time. - -*`--hibernate`* -: Hibernate computer now. Can be combined with *`--sleep`* for suspend then hibernate after X amount of time. - -*`--lock`* -: Lock screen. - -# FILES - -*``~/.config/powerkit/powerkit.conf``* -: Per user configuration file. - -# SEE ALSO - -**``xsecurelock``**(1), **``UPower``**(7), **``systemd-logind``**(8) - -# BUGS - -See **https://github.com/rodlie/powerkit/issues**. - -# COPYRIGHT - -``` -Copyright (c) Ole-André Rodlie -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -* Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -* Neither the name of the copyright holder nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -``` +See [documentation](powerkit.md) (`man powerkit`) for more information. diff --git a/docs/build.sh b/docs/build.sh index 4ac0e5b..f600daa 100755 --- a/docs/build.sh +++ b/docs/build.sh @@ -13,6 +13,6 @@ VERSION=`cat ${CWD}/CMakeLists.txt | sed '/powerkit VERSION/!d;s/)//' | awk '{pr echo "% POWERKIT(1) Version ${VERSION} | PowerKit Documentation" > ${CWD}/tmp.md echo "% Ole-André Rodlie" >> ${CWD}/tmp.md echo "% ${MONTH} ${YEAR}" >> ${CWD}/tmp.md -cat ${CWD}/docs/README.md >> ${CWD}/tmp.md +cat ${CWD}/docs/powerkit.md >> ${CWD}/tmp.md ${PANDOC} ${CWD}/tmp.md -s -t man > ${CWD}/docs/powerkit.1 rm ${CWD}/tmp.md diff --git a/docs/powerkit.md b/docs/powerkit.md new file mode 100644 index 0000000..197a90c --- /dev/null +++ b/docs/powerkit.md @@ -0,0 +1,230 @@ +# NAME + +*powerkit* - Desktop independent power manager for Linux + +# SYNOPSIS + +powerkit *`[--config]`* *`[--set-brightness-up]`* *`[--set-brightness-down]`* *`[--sleep]`* *`[--hibernate]`* *`[--lock]`* + +# DESCRIPTION + +Desktop independent power manager for use with alternative X11 desktop environments and window managers on Linux. + + * Implements *``org.freedesktop.ScreenSaver``* service + * Implements *``org.freedesktop.PowerManagement.Inhibit``* service + * Automatic actions on lid, idle and low battery + * Sleep + * Hibernate + * HybridSleep + * Suspend then Hibernate + * Shutdown + * Screen saver support + * Screen lid support + * Screen locking support + * Screen backlight support + * Notification support (can use *``org.freedesktop.Notifications``* if available) + +# USAGE + +powerkit should be started during the X11 user session. Consult the documentation for your desktop environment or window manager for launching startup applications. + + * In *Fluxbox* add *``powerkit &``* to the *``~/.fluxbox/startup``* file + * In *Openbox* add *``powerkit &``* to the *``~/.config/openbox/autostart``* file. + +**Do use powerkit if your desktop environment or window manager already has a power manager or screen saver service running.** + +## CONFIGURATION + +Settings are available directly from the system tray icon or run *``powerkit --config``*. You should also be able to lauch the powerkit settings from your desktop application menu (if available). + +## SCREEN SAVER + +powerkit implements a basic screen saver to handle screen blanking, poweroff and locking feature. + +Locking feature depends on ``xsecurelock``. + +You can override the lock command with *``screensaver_lock_cmd=``* in *`~/.config/powerkit/powerkit.conf`*. Note that the command must not contain spaces. + +## BACKLIGHT + +The current display brightness (on laptops and supported displays) can be adjusted with the mouse wheel on the system tray icon or through the system tray menu. + +powerkit also supports the following commands that can be used for global shortcuts, scripts etc: + +*`powerkit --set-brightness-up`* +: Set default display brightness up. + +*`powerkit --set-brightness-down`* +: Set default display brightness down. + +On Fluxbox you can add the commands to the *`~/.fluxbox/keys`* file: + +``` +XF86MonBrightnessUp :Exec powerkit --set-brightness-up +XF86MonBrightnessDown :Exec powerkit --set-brightness-down +``` + +## HIBERNATE + +If hibernate works depends on your system, a swap partition (or file) is needed by the kernel to support hibernate. + +***Consult your system documentation regarding hibernation***. + +## ICONS + +powerkit will use the existing icon theme from the running desktop environment or window manager. + +You can override the icon theme in the *`~/.config/powerkit/powerkit.conf`* file, use *``icon_theme=``*. + +# FAQ + +## How does an application inhibit the screen saver? + +The preferred way to inhibit the screen saver from an application is to use the *org.freedesktop.ScreenSaver* specification. Any application that uses *org.freedesktop.ScreenSaver* will work with powerkit. + +Popular applications that uses this feature is Mozilla Firefox, Google Chrome, VideoLAN VLC and many more. + +## How does an application inhibit suspend actions? + +The preferred way to inhibit suspend actions from an application is to use the *org.freedesktop.PowerManagement* specification. Any application that uses *org.freedesktop.PowerManagement* will work with powerkit. + +Common use cases are audio playback, downloading, rendering and similar. + +## Google Chrome/Chromium does not inhibit the screen saver or power manager!? + +Chrome does not use *org.freedesktop.ScreenSaver* or *org.freedesktop.PowerManagement* until it detects a supported desktop environment. Add the following to *``~/.bashrc``* or the *``google-chrome``* launcher if you don't run a supported desktop environment: + +``` +export DESKTOP_SESSION=xfce +export XDG_CURRENT_DESKTOP=xfce +``` + +## Mozilla Firefox does not inhibit the power manager during audio playback and/or downloading!? + +This is an issue with Firefox (missing feature). Use a different browser or open a request on the Firefox issue tracker. + +Firefox should inhibit the power manager during audio playback (regardless of video) and during download (active queue). Currently Firefox only inhibit the screen saver during video playback. Chrome/Chromium does this correctly. + +# REQUIREMENTS + +powerkit requires the following dependencies: + + * *[X11](https://www.x.org)* + * *[libXss](https://www.x.org/archive//X11R7.7/doc/man/man3/Xss.3.xhtml)* + * *[libXrandr](https://www.x.org/wiki/libraries/libxrandr/)* + * *[Qt](https://qt.io)* 5.15 *(Core/DBus/Gui/Widgets)* + * *[logind](https://www.freedesktop.org/wiki/Software/systemd/logind/)* *(or compatible service)* + * *[UPower](https://upower.freedesktop.org/)* *(or compatible service)* + * *[xsecurelock](https://github.com/google/xsecurelock)* + +# BUILD + +First make sure you have the required dependencies installed, then review the most common build options: + + * *``CMAKE_INSTALL_PREFIX=``* - Install target. *``/usr``* recommended. + * *``CMAKE_BUILD_TYPE=``* - Build type. *``Release``* recommended + +Now configure powerkit with CMake and build: + +``` +mkdir build && cd build +cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release .. +make -j4 +``` + +All you need is the *``powerkit``* binary located in the build directory, you can run it from any location. + +## Install + +Use regular *``make install``* with optional *``DESTDIR``*: + +``` +make DESTDIR= install +``` + +or make a native package: + +``` +cpack -G DEB +``` +``` +cpack -G RPM +``` + +# CHANGELOG + +## 2.0.0 (TBA) + + * Recommended locker is ``xsecurelock`` + * Added support for "modern" logind + * Removed support for ConsoleKit + * Removed support for XScreenSaver + * Added basic screen saver + * Easier to use (minimal/no setup) + * New UI + * Major code changes + +# OPTIONS + +*``--config``* +: Launch configuration. + +*`--set-brightness-up`* +: Set default display brightness up. + +*`--set-brightness-down`* +: Set default display brightness down. + +*`--sleep`* +: Suspend computer now. Can be combined with *`--hibernate`* for suspend then hibernate after X amount of time. + +*`--hibernate`* +: Hibernate computer now. Can be combined with *`--sleep`* for suspend then hibernate after X amount of time. + +*`--lock`* +: Lock screen. + +# FILES + +*``~/.config/powerkit/powerkit.conf``* +: Per user configuration file. + +# SEE ALSO + +**``xsecurelock``**(1), **``UPower``**(7), **``systemd-logind``**(8) + +# BUGS + +See **https://github.com/rodlie/powerkit/issues**. + +# COPYRIGHT + +``` +Copyright (c) Ole-André Rodlie +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +* Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +* Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +``` diff --git a/docs/screenshot.png b/docs/screenshot.png new file mode 100644 index 0000000..fa7a919 Binary files /dev/null and b/docs/screenshot.png differ