NAME¶
X11::Protocol::Ext::MIT_SCREEN_SAVER - external screen saver support
SYNOPSIS¶
use X11::Protocol;
my $X = X11::Protocol->new;
$X->init_extension('MIT-SCREEN-SAVER')
or print "MIT-SCREEN-SAVER extension not available";
DESCRIPTION¶
The MIT-SCREEN-SAVER extension allows a client screen saver program to draw a
screen saver. Any client can listen for screen saver activation too.
A screen saver program registers itself and desired window attributes with
"MitScreenSaverSetAttributes()" and selects saver notify events with
"MitScreenSaverSelectInput()". There can only be one external saver
program at any one time.
See
examples/mit-screen-saver-external.pl in the X11-Protocol-Other
sources for a complete screen saver program.
See the core "SetScreenSaver()" for the usual screen idle timeout,
saver cycle period, and the "Blank" or "Internal" builtin
saver styles. See the core "ForceScreenSaver()" to forcibly turn on
the screen saver.
REQUESTS¶
The following requests are made available with an "init_extension()"
per "EXTENSIONS" in X11::Protocol.
my $bool = $X->init_extension('MIT-SCREEN-SAVER');
- "($server_major, $server_minor) = $X->MitScreenSaverQueryVersion
($client_major, $client_minor)"
- Negotiate a protocol version with the server. $client_major and
$client_minor is what the client would like, the returned $server_major
and $server_minor is what the server will do, which will be the closest to
the client requested version that the server supports.
The code in this module supports 1.0. The intention would be to
automatically negotiate within "init_extension()" if/when
necessary.
- "($state, $window, $til_or_since, $idle, $event_mask, $kind) =
$X->MitScreenSaverQueryInfo ($drawable)"
- Return information about the screen saver on the screen of $drawable (an
integer XID).
$state is an enum string "Off", "On", or
"Disabled", per "MitScreenSaverState" below.
$window is the screen saver window, or "None". When this window
exists it's an override-redirect child of the root window but it doesn't
appear in the "QueryTree()" children of the root. This window
exists when an External saver is activated but might not exist at other
times (in which case $window is "None").
$til_or_since is a period in milliseconds. If $state is "Off" then
it's how long until the saver will be activated due to idle. If $state is
"On" then it's how long in milliseconds since the saver was
activated. But see "BUGS" below.
$idle is how long in milliseconds the screen has been idle. In the X.org
servers this is also available as an "IDLETIME" counter in the
SYNC extension (see X11::Protocol::Ext::SYNC).
$event_mask is the current client's mask as set by
"MitScreenSaverSelectInput()" below.
$kind is an enum string "Blanked", "Internal" or
"External" for how the saver is being done now or how it will be
done when next activated, per "MitScreenSaverKind" below.
- "$X->MitScreenSaverSelectInput ($drawable, $event_mask)"
- Select "MitScreenSaverNotify" events from the screen of
$drawable (an XID). $event_mask has two bits,
bitpos bitval
NotifyMask 0 0x01
CycleMask 1 0x02
There's no pack function for these yet, so just give the integer bitvals,
for example 0x03 for both.
- "$X->MitScreenSaverSetAttributes ($drawable, $class, $depth,
$visual, $x, $y, $width, $height, $border_width, key => value,
...)"
- Setup the screen saver window on the screen of $drawable (an XID).
The arguments are the same as the core "CreateWindow()", except
there's no new XID to create and the parent window is always the root
window on the screen of $drawable ($drawable could be the root window
already).
This setup makes the saver "External" kind on its next activation.
If the saver is currently active then it's not changed. The client can
listen for "MitScreenSaverNotify" (see "EVENTS" below)
to know when the saver is activated. The saver window XID is reported in
that Notify and exposures etc can be selected on it at that time to know
when to draw, unless perhaps a background pixel or pixmap in this
"MitScreenSaverSetAttributes()" is enough.
Only one client at a time can setup a saver window like this. If another has
done so then an "Access" error results.
- "$X->MitScreenSaverUnsetAttributes ($drawable)"
- Unset the screen saver window. If the client did not set the window then
do nothing.
This changes the saver from "External" kind back to the server
builtin. If the screen saver is currently active then that happens
immediately.
At client shutdown an Unset is done automatically, unless
"RetainPermanent" closedown mode.
EVENTS¶
"MitScreenSaverNotify" events are sent to the client when selected by
"MitScreenSaverSelectInput()" above. These events report when the
screen saver state changes. The event has the usual fields
name "MitScreenSaverNotify"
synthetic true if from a SendEvent
code integer opcode
sequence_number integer
and event-specific fields
state "Off", "On", "Cycle"
time server timestamp (integer)
root root window of affected screen (XID)
window the screen saver window (XID)
kind "Blanked", "Internal", "External"
forced integer 0 or 1
"state" is "Off" if the saver has turned off or
"On" if it turned on. "forced" is 1 if the change was due
to a "ForceScreenSaver()" request rather than user
activity/inactivity. On/Off events are selected by NotifyMask to
"MitScreenSaverSelectInput()" above.
"state" is "Cycle" if the saver cycling period has expired,
which means it's time to show something different. This is selected by
CycleMask to "MitScreenSaverSelectInput()" above.
"kind" is the current saver kind per "MitScreenSaverKind"
below.
ENUM TYPES¶
The following types are available for "$X->interp()" and
"$X->num()" after "init_extension()".
- MitScreenSaverKind
-
"Blanked" 0 video output turned off
"Internal" 1 server builtin saver
"External" 2 external saver client
- MitScreenSaverState
- The state of the screen saver, as returned by
"MitScreenSaverQueryInfo()" and in
"MitScreenSaverNotify" events.
"Off" 0
"On" 1
"Cycle" 2
"Disabled" 3
For example,
my $num = $X->num("MitScreenSaverKind", "External");
# sets $num to 2
BUGS¶
In XFree86 and X.org servers through to circa X.org 1.10, if the screen saver is
activated with a "ForceScreenSaver()" request then the $til_or_since
from "MitScreenSaverQueryInfo()" is a big number, apparently being a
negative for the future time when it would have activated due to idle. There's
no attempt to do anything about that here.
Also in these servers when the saver is "On" the idle timeout
apparently continues to fire too, so the "since" of $til_or_since is
only since the last firing, as if screen saver was re-activated, not the time
since first activated, or something like that.
SEE ALSO¶
X11::Protocol, X11::Protocol::Ext::DPMS
/usr/share/doc/x11proto-scrnsaver-dev/saver.txt.gz
xset(1), for setting the core screen saver parameters from the command
line.
xscreensaver(1),
xprintidle(1), X11::IdleTime
HOME PAGE¶
<
http://user42.tuxfamily.org/x11-protocol-other/index.html>
LICENSE¶
Copyright 2011, 2012, 2013 Kevin Ryde
X11-Protocol-Other is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 3, or (at your option) any later version.
X11-Protocol-Other is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
details.
You should have received a copy of the GNU General Public License along with
X11-Protocol-Other. If not, see <
http://www.gnu.org/licenses/>.