Screensaver::Any - Common interface to screensaver/screenlocker functions
This document describes version 0.007 of Screensaver::Any (from Perl distribution Screensaver-Any), released on 2019-09-04.
This module provides common functions related to screensaver.
Supported screensavers: KDE Plasma's kscreenlocker (kde), GNOME screensaver (gnome), Cinnamon screensaver (cinnamon), and xscreensaver. Support for more screensavers, e.g. Windows is more than welcome.
In GNOME 3.8 and later, gnome-screensaver command has been removed (one of the reasons is consideration of the eventual move to Wayland). Locking/unlocking screen can be done if you install gnome-screensaver separately, or use other screensaver like xscreensaver, or use gdm (in which case you can use a command like dbus-send --type=method_call --dest=org.gnome.ScreenSaver /org/gnome/ScreenSaver org.gnome.ScreenSaver.Lock).
dbus-send --type=method_call --dest=org.gnome.ScreenSaver /org/gnome/ScreenSaver org.gnome.ScreenSaver.Lock
activate_screensaver(%args) -> [status, msg, payload, meta]
Activate screensaver immediately and lock screen.
This function is not exported by default, but exportable.
Arguments ('*' denotes required arguments):
screensaver => str
Explicitly set screensaver program to use.
The default, when left undef, is to detect what screensaver is running,
Returns an enveloped result (an array).
First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.
Return value: (any)
deactivate_screensaver(%args) -> [status, msg, payload, meta]
Deactivate screensaver and unblank the screen.
If screen is not being blank (screensaver is not activated) then nothing happens. If screen is being blanked (screensaver is activated) then unblank the screen.
Often the screen is also locked when being blanked. On some screensavers, like xscreensaver, deactivating won't unlock the screen and user will need to unlock the screen herself first. Some other screensavers, like GNOME/cinnamon, will happily unlock the screen automatically.
detect_screensaver() -> str
Detect which screensaver program is currently running.
Will return a string containing name of screensaver program, e.g. kde, gnome, cinnamon, xscreensaver. Will return undef if no known screensaver is detected.
Return value: (str)
disable_screensaver(%args) -> [status, msg, payload, meta]
Disable screensaver so screen will not go blank or lock after being idle.
enable_screensaver(%args) -> [status, msg, payload, meta]
Enable screensaver that has been previously disabled.
get_screensaver_timeout(%args) -> [status, msg, payload, meta]
Get screensaver idle timeout, in number of seconds.
Return value: Timeout value, in seconds (float)
prevent_screensaver_activated() -> [status, msg, payload, meta]
Prevent screensaver from being activated by resetting idle timer.
You can use this function to prevent screensaver from being activated, if it is not yet being activated. This is usually done by resetting the idle counter. With KDE, this is called "simulating user activity". With xscreensaver, one can use the -deactivate on the CLI.
This function will need to be run periodically and often enough (more often than the idle timeout period) to actually keep the screensaver from ever being activated.
If screensaver is already activated, then nothing happens.
screensaver_is_active(%args) -> [status, msg, payload, meta]
Check if screensaver is being activated.
screensaver_is_enabled(%args) -> [status, msg, payload, meta]
Check whether screensaver is enabled.
set_screensaver_timeout(%args) -> [status, msg, payload, meta]
Set screensaver idle timeout.
Set timeout to 5 minutes:
set_screensaver_timeout( timeout => 300);
To set timeout for xscreensaver, the program finds this line in ~/.xscreensaver:
modifies the line, save the file, and HUP the xscreensaver process.
To set timeout for gnome screensaver, the program executes this command:
gsettings set org.gnome.desktop.session idle-delay 300
Not yet supported.
To set timeout for the KDE screen locker, the program looks for this line in ~/.kde/share/config/kscreensaverrc:
modifies the line, save the file.
timeout => duration
Please visit the project's homepage at https://metacpan.org/release/Screensaver-Any.
Source repository is at https://github.com/perlancar/perl-Screensaver-Any.
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Screensaver-Any
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
This software is copyright (c) 2019, 2018, 2017 by email@example.com.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Screensaver::Any, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell
For more information on module installation, please visit the detailed CPAN module installation guide.