/ 
X11-Protocol-Other-8
/ X11::Protocol::Ext::MIT_SCREEN_SAVER

NAME

X11::Protocol::Ext::MIT_SCREEN_SAVER - external screen saver support

SYNOPSIS

use X11::Protocol;
$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 the screen saver image. Other clients can listen for screen saver activation too.

See the core SetScreenSaver for the idle timeout, cycle period, and the "Blank" or "Internal" builtin saving, and see the core ForceScreenSaver for forcibly turning 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 current code in this module supports 1.0 and the intention is 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 XID).

$state is an enum string "Off", "On", or "Disabled".

$window is the screen saver window, or "None". It might exist always, or might be created only for "External" or only when required, etc. In any case it's an override-redirect child of the root window but does not appear in the QueryTree children.

$til_or_since is a time in milliseconds. If $state is "Off" then it's how long until the saver will be activated due to idle. Or if $state is "On" then how long in milliseconds since it was activated. (But see "BUGS" below.)

$idle is how long in milliseconds the screen has been idle.

$event_mask is the current client's mask per MitScreenSaverSelectInput below.

$kind is an enum string for how the saver is being done, or will be done when next activated,

"Blanked"     video output turned off
"Internal"    server builtin saver
"External"    external saver client
$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 an integer, 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.

This setup makes the saver "External" kind on its next activation. If currently active then it's not changed. The client can listen for MitScreenSaverNotify (see "EVENTS" below) to know when the saver is activated and should be drawn (unless a background pixel or pixmap in this create is enough). The saver window XID is reported in that Notify.

Only one client at a time can setup a saver window this way. If another has done so then an Access error results.

$window = $X->MitScreenSaverUnsetAttributes ($drawable)

Unset the screen saver window. If the client did not set it up 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, except for RetainPermanent closedown mode.

EVENTS

MitScreenSaverNotify events are sent to the client when selected by MitScreenSaverSelectInput above. It reports 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         enum, "Off", "On", "Cycle"
time          integer, server timestamp
root          XID, root window of affected screen
window        XID, the screen saver window
kind          enum, "Blanked", "Internal", "External"
forced        integer boolean

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 the NotifyMask to MitScreenSaverSelectInput() above.

state is "Cycle" if the saver cycling period has expired, which means time to show something different. This is selected by CycleMask to MitScreenSaverSelectInput() above.

kind is the current saver mechanism, as described under MitScreenSaverQueryInfo above.

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 a negative to the future time when it would have activated due to idle. There's no attempt to do anything about that here.

While "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

xset(1), for setting the core screen saver parameters from the command line.

xscreensaver(1)

HOME PAGE

http://user42.tuxfamily.org/x11-protocol-other/index.html

LICENSE

Copyright 2011 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/>.