/ 
Screensaver-Any-0.007
River stage one • 2 direct dependents • 2 total dependents
/ Screensaver::Any

NAME

Screensaver::Any - Common interface to screensaver/screenlocker functions

VERSION

This document describes version 0.007 of Screensaver::Any (from Perl distribution Screensaver-Any), released on 2019-09-04.

DESCRIPTION

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.

NOTES

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).

FUNCTIONS

activate_screensaver

Usage:

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

Usage:

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.

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)

detect_screensaver

Usage:

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.

This function is not exported by default, but exportable.

No arguments.

Return value: (str)

disable_screensaver

Usage:

disable_screensaver(%args) -> [status, msg, payload, meta]

Disable screensaver so screen will not go blank or lock after being idle.

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)

enable_screensaver

Usage:

enable_screensaver(%args) -> [status, msg, payload, meta]

Enable screensaver that has been previously disabled.

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)

get_screensaver_timeout

Usage:

get_screensaver_timeout(%args) -> [status, msg, payload, meta]

Get screensaver idle timeout, in number of seconds.

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: Timeout value, in seconds (float)

prevent_screensaver_activated

Usage:

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.

This function is not exported by default, but exportable.

No arguments.

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)

screensaver_is_active

Usage:

screensaver_is_active(%args) -> [status, msg, payload, meta]

Check if screensaver is being activated.

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)

screensaver_is_enabled

Usage:

screensaver_is_enabled(%args) -> [status, msg, payload, meta]

Check whether screensaver is enabled.

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)

set_screensaver_timeout

Usage:

set_screensaver_timeout(%args) -> [status, msg, payload, meta]

Set screensaver idle timeout.

Examples:

  • Set timeout to 5 minutes:

    set_screensaver_timeout( timeout => 300);

  • xscreensaver

    To set timeout for xscreensaver, the program finds this line in ~/.xscreensaver:

    timeout:    0:05:00

    modifies the line, save the file, and HUP the xscreensaver process.

  • gnome

    To set timeout for gnome screensaver, the program executes this command:

    gsettings set org.gnome.desktop.session idle-delay 300

  • cinnamon

    Not yet supported.

  • KDE

    To set timeout for the KDE screen locker, the program looks for this line in ~/.kde/share/config/kscreensaverrc:

    Timeout=300

    modifies the line, save the file.

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,

  • timeout => duration

    Value.

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: Timeout value, in seconds (float)

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Screensaver-Any.

SOURCE

Source repository is at https://github.com/perlancar/perl-Screensaver-Any.

BUGS

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.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019, 2018, 2017 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.