.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "X11::Protocol::Ext::MIT_SCREEN_SAVER 3pm" .TH X11::Protocol::Ext::MIT_SCREEN_SAVER 3pm "2019-08-26" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" X11::Protocol::Ext::MIT_SCREEN_SAVER \- external screen saver support .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& use X11::Protocol; \& my $X = X11::Protocol\->new; \& $X\->init_extension(\*(AqMIT\-SCREEN\-SAVER\*(Aq) \& or print "MIT\-SCREEN\-SAVER extension not available"; .Ve .SH "DESCRIPTION" .IX Header "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. .PP A screen saver program registers itself and desired window attributes with \&\f(CW\*(C`MitScreenSaverSetAttributes()\*(C'\fR and selects saver notify events with \&\f(CW\*(C`MitScreenSaverSelectInput()\*(C'\fR. There can only be one external saver program at any one time. .PP See \fIexamples/mit\-screen\-saver\-external.pl\fR for a complete screen saver program. .PP See the core \f(CW\*(C`SetScreenSaver()\*(C'\fR for the usual screen idle timeout, saver cycle period, and the \*(L"Blank\*(R" or \*(L"Internal\*(R" builtin saver styles. See the core \f(CW\*(C`ForceScreenSaver()\*(C'\fR to forcibly turn on the screen saver. .SH "REQUESTS" .IX Header "REQUESTS" The following requests are made available with an \f(CW\*(C`init_extension()\*(C'\fR per \&\*(L"\s-1EXTENSIONS\*(R"\s0 in X11::Protocol. .PP .Vb 1 \& my $bool = $X\->init_extension(\*(AqMIT\-SCREEN\-SAVER\*(Aq); .Ve .ie n .IP """($server_major, $server_minor) = $X\->MitScreenSaverQueryVersion ($client_major, $client_minor)""" 4 .el .IP "\f(CW($server_major, $server_minor) = $X\->MitScreenSaverQueryVersion ($client_major, $client_minor)\fR" 4 .IX Item "($server_major, $server_minor) = $X->MitScreenSaverQueryVersion ($client_major, $client_minor)" Negotiate a protocol version with the server. \f(CW$client_major\fR and \&\f(CW$client_minor\fR is what the client would like, the returned \&\f(CW$server_major\fR and \f(CW$server_minor\fR is what the server will do, which will be the closest to the client requested version that the server supports. .Sp The code in this module supports 1.0. The intention would be to automatically negotiate within \f(CW\*(C`init_extension()\*(C'\fR if/when necessary. .ie n .IP """($state, $window, $til_or_since, $idle, $event_mask, $kind) = $X\->MitScreenSaverQueryInfo ($drawable)""" 4 .el .IP "\f(CW($state, $window, $til_or_since, $idle, $event_mask, $kind) = $X\->MitScreenSaverQueryInfo ($drawable)\fR" 4 .IX Item "($state, $window, $til_or_since, $idle, $event_mask, $kind) = $X->MitScreenSaverQueryInfo ($drawable)" Return information about the screen saver on the screen of \f(CW$drawable\fR (an integer \s-1XID\s0). .Sp \&\f(CW$state\fR is an enum string \*(L"Off\*(R", \*(L"On\*(R", or \*(L"Disabled\*(R", per \&\*(L"MitScreenSaverState\*(R" below. .Sp \&\f(CW$window\fR is the screen saver window, or \*(L"None\*(R". When this window exists it's an override-redirect child of the root window but it doesn't appear in the \f(CW\*(C`QueryTree()\*(C'\fR children of the root. This window exists when an External saver is activated but might not exist at other times (in which case \f(CW$window\fR is \*(L"None\*(R"). .Sp \&\f(CW$til_or_since\fR is a period in milliseconds. If \f(CW$state\fR is \*(L"Off\*(R" then it's how long until the saver will be activated due to idle. If \f(CW$state\fR is \*(L"On\*(R" then it's how long in milliseconds since the saver was activated. But see \*(L"\s-1BUGS\*(R"\s0 below. .Sp \&\f(CW$idle\fR is how long in milliseconds the screen has been idle. In the X.org servers this is also available as an \*(L"\s-1IDLETIME\*(R"\s0 counter in the \s-1SYNC\s0 extension (see X11::Protocol::Ext::SYNC). .Sp \&\f(CW$event_mask\fR is the current client's mask as set by \&\f(CW\*(C`MitScreenSaverSelectInput()\*(C'\fR below. .Sp \&\f(CW$kind\fR is an enum string \*(L"Blanked\*(R", \*(L"Internal\*(R" or \*(L"External\*(R" for how the saver is being done now or how it will be done when next activated, per \&\*(L"MitScreenSaverKind\*(R" below. .ie n .IP """$X\->MitScreenSaverSelectInput ($drawable, $event_mask)""" 4 .el .IP "\f(CW$X\->MitScreenSaverSelectInput ($drawable, $event_mask)\fR" 4 .IX Item "$X->MitScreenSaverSelectInput ($drawable, $event_mask)" Select \f(CW\*(C`MitScreenSaverNotify\*(C'\fR events from the screen of \f(CW$drawable\fR (an \&\s-1XID\s0). \f(CW$event_mask\fR has two bits, .Sp .Vb 3 \& bitpos bitval \& NotifyMask 0 0x01 \& CycleMask 1 0x02 .Ve .Sp There's no pack function for these yet, so just give the integer bitvals, for example 0x03 for both. .ie n .IP """$X\->MitScreenSaverSetAttributes ($drawable, $class, $depth, $visual, $x, $y, $width, $height, $border_width, key => value, ...)""" 4 .el .IP "\f(CW$X\->MitScreenSaverSetAttributes ($drawable, $class, $depth, $visual, $x, $y, $width, $height, $border_width, key => value, ...)\fR" 4 .IX Item "$X->MitScreenSaverSetAttributes ($drawable, $class, $depth, $visual, $x, $y, $width, $height, $border_width, key => value, ...)" Setup the screen saver window on the screen of \f(CW$drawable\fR (an \s-1XID\s0). .Sp The arguments are the same as the core \f(CW\*(C`CreateWindow()\*(C'\fR, except there's no new \s-1XID\s0 to create and the parent window is always the root window on the screen of \f(CW$drawable\fR (\f(CW$drawable\fR could be the root window already). .Sp This setup makes the saver \*(L"External\*(R" kind on its next activation. If the saver is currently active then it's not changed. The client can listen for \&\f(CW\*(C`MitScreenSaverNotify\*(C'\fR (see \*(L"\s-1EVENTS\*(R"\s0 below) to know when the saver is activated. The saver window \s-1XID\s0 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 \f(CW\*(C`MitScreenSaverSetAttributes()\*(C'\fR is enough. .Sp Only one client at a time can setup a saver window like this. If another has done so then an \f(CW\*(C`Access\*(C'\fR error results. .ie n .IP """$X\->MitScreenSaverUnsetAttributes ($drawable)""" 4 .el .IP "\f(CW$X\->MitScreenSaverUnsetAttributes ($drawable)\fR" 4 .IX Item "$X->MitScreenSaverUnsetAttributes ($drawable)" Unset the screen saver window. If the client did not set the window then do nothing. .Sp This changes the saver from \*(L"External\*(R" kind back to the server builtin. If the screen saver is currently active then that happens immediately. .Sp At client shutdown an Unset is done automatically, unless \f(CW\*(C`RetainPermanent\*(C'\fR closedown mode. .SH "EVENTS" .IX Header "EVENTS" \&\f(CW\*(C`MitScreenSaverNotify\*(C'\fR events are sent to the client when selected by \&\f(CW\*(C`MitScreenSaverSelectInput()\*(C'\fR above. These events report when the screen saver state changes. The event has the usual fields .PP .Vb 4 \& name "MitScreenSaverNotify" \& synthetic true if from a SendEvent \& code integer opcode \& sequence_number integer .Ve .PP and event-specific fields .PP .Vb 6 \& 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 .Ve .PP \&\f(CW\*(C`state\*(C'\fR is \*(L"Off\*(R" if the saver has turned off or \*(L"On\*(R" if it turned on. \&\f(CW\*(C`forced\*(C'\fR is 1 if the change was due to a \f(CW\*(C`ForceScreenSaver()\*(C'\fR request rather than user activity/inactivity. On/Off events are selected by NotifyMask to \&\f(CW\*(C`MitScreenSaverSelectInput()\*(C'\fR above. .PP \&\f(CW\*(C`state\*(C'\fR is \*(L"Cycle\*(R" if the saver cycling period has expired, which means it's time to show something different. This is selected by CycleMask to \&\f(CW\*(C`MitScreenSaverSelectInput()\*(C'\fR above. .PP \&\f(CW\*(C`kind\*(C'\fR is the current saver kind per \*(L"MitScreenSaverKind\*(R" below. .SH "ENUM TYPES" .IX Header "ENUM TYPES" The following types are available for \f(CW\*(C`$X\->interp()\*(C'\fR and \&\f(CW\*(C`$X\->num()\*(C'\fR after \f(CW\*(C`init_extension()\*(C'\fR. .IP "MitScreenSaverKind" 4 .IX Item "MitScreenSaverKind" .Vb 3 \& "Blanked" 0 video output turned off \& "Internal" 1 server builtin saver \& "External" 2 external saver client .Ve .IP "MitScreenSaverState" 4 .IX Item "MitScreenSaverState" The state of the screen saver, as returned by \f(CW\*(C`MitScreenSaverQueryInfo()\*(C'\fR and in \f(CW\*(C`MitScreenSaverNotify\*(C'\fR events. .Sp .Vb 4 \& "Off" 0 \& "On" 1 \& "Cycle" 2 \& "Disabled" 3 .Ve .PP For example, .PP .Vb 2 \& my $num = $X\->num("MitScreenSaverKind", "External"); \& # sets $num to 2 .Ve .SH "BUGS" .IX Header "BUGS" In XFree86 and X.org servers through to circa X.org 1.10, if the screen saver is activated with a \f(CW\*(C`ForceScreenSaver()\*(C'\fR request then the \&\f(CW$til_or_since\fR from \f(CW\*(C`MitScreenSaverQueryInfo()\*(C'\fR 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. .PP Also in these servers when the saver is \*(L"On\*(R" the idle timeout apparently continues to fire too, so the \*(L"since\*(R" of \f(CW$til_or_since\fR is only since the last firing, as if screen saver was re-activated, not the time since first activated, or something like that. .SH "SEE ALSO" .IX Header "SEE ALSO" X11::Protocol, X11::Protocol::Ext::DPMS .PP \&\fI/usr/share/doc/x11proto\-scrnsaver\-dev/saver.txt.gz\fR .PP \&\fBxset\fR\|(1), for setting the core screen saver parameters from the command line. .PP \&\fBxscreensaver\fR\|(1), \fBxssstate\fR\|(1), \fBxprintidle\fR\|(1), X11::IdleTime .SH "HOME PAGE" .IX Header "HOME PAGE" .SH "LICENSE" .IX Header "LICENSE" Copyright 2011, 2012, 2013, 2014, 2016, 2017 Kevin Ryde .PP X11\-Protocol\-Other is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version. .PP X11\-Protocol\-Other is distributed in the hope that it will be useful, but \&\s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the \s-1GNU\s0 General Public License for more details. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with X11\-Protocol\-Other. If not, see .