X11::Protocol::Ext::MIT_SCREEN_SAVER(3pm)

1X11::Protocol::Ext::MITU_sSeCrRECEoNn_tSrAiVbEuRt(e3d)PXe1r1l::DPorcoutmoecnotla:t:iEoxnt::MIT_SCREEN_SAVER(3)
2
3
4

NAME

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

SYNOPSIS

9        use X11::Protocol;
10        my $X = X11::Protocol->new;
11        $X->init_extension('MIT-SCREEN-SAVER')
12          or print "MIT-SCREEN-SAVER extension not available";
13

DESCRIPTION

15       The MIT-SCREEN-SAVER extension allows a client screen saver program to
16       draw a screen saver.  Any client can listen for screen saver activation
17       too.
18
19       A screen saver program registers itself and desired window attributes
20       with "MitScreenSaverSetAttributes()" and selects saver notify events
21       with "MitScreenSaverSelectInput()".  There can only be one external
22       saver program at any one time.
23
24       See examples/mit-screen-saver-external.pl for a complete screen saver
25       program.
26
27       See the core "SetScreenSaver()" for the usual screen idle timeout,
28       saver cycle period, and the "Blank" or "Internal" builtin saver styles.
29       See the core "ForceScreenSaver()" to forcibly turn on the screen saver.
30

REQUESTS

32       The following requests are made available with an "init_extension()"
33       per "EXTENSIONS" in X11::Protocol.
34
35           my $bool = $X->init_extension('MIT-SCREEN-SAVER');
36
37       "($server_major, $server_minor) = $X->MitScreenSaverQueryVersion
38       ($client_major, $client_minor)"
39           Negotiate a protocol version with the server.  $client_major and
40           $client_minor is what the client would like, the returned
41           $server_major and $server_minor is what the server will do, which
42           will be the closest to the client requested version that the server
43           supports.
44
45           The code in this module supports 1.0.  The intention would be to
46           automatically negotiate within "init_extension()" if/when
47           necessary.
48
49       "($state, $window, $til_or_since, $idle, $event_mask, $kind) =
50       $X->MitScreenSaverQueryInfo ($drawable)"
51           Return information about the screen saver on the screen of
52           $drawable (an integer XID).
53
54           $state is an enum string "Off", "On", or "Disabled", per
55           "MitScreenSaverState" below.
56
57           $window is the screen saver window, or "None".  When this window
58           exists it's an override-redirect child of the root window but it
59           doesn't appear in the "QueryTree()" children of the root.  This
60           window exists when an External saver is activated but might not
61           exist at other times (in which case $window is "None").
62
63           $til_or_since is a period in milliseconds.  If $state is "Off" then
64           it's how long until the saver will be activated due to idle.  If
65           $state is "On" then it's how long in milliseconds since the saver
66           was activated.  But see "BUGS" below.
67
68           $idle is how long in milliseconds the screen has been idle.  In the
69           X.org servers this is also available as an "IDLETIME" counter in
70           the SYNC extension (see X11::Protocol::Ext::SYNC).
71
72           $event_mask is the current client's mask as set by
73           "MitScreenSaverSelectInput()" below.
74
75           $kind is an enum string "Blanked", "Internal" or "External" for how
76           the saver is being done now or how it will be done when next
77           activated, per "MitScreenSaverKind" below.
78
79       "$X->MitScreenSaverSelectInput ($drawable, $event_mask)"
80           Select "MitScreenSaverNotify" events from the screen of $drawable
81           (an XID).  $event_mask has two bits,
82
83                             bitpos  bitval
84               NotifyMask      0      0x01
85               CycleMask       1      0x02
86
87           There's no pack function for these yet, so just give the integer
88           bitvals, for example 0x03 for both.
89
90       "$X->MitScreenSaverSetAttributes ($drawable, $class, $depth, $visual,
91       $x, $y, $width, $height, $border_width, key => value, ...)"
92           Setup the screen saver window on the screen of $drawable (an XID).
93
94           The arguments are the same as the core "CreateWindow()", except
95           there's no new XID to create and the parent window is always the
96           root window on the screen of $drawable ($drawable could be the root
97           window already).
98
99           This setup makes the saver "External" kind on its next activation.
100           If the saver is currently active then it's not changed.  The client
101           can listen for "MitScreenSaverNotify" (see "EVENTS" below) to know
102           when the saver is activated.  The saver window XID is reported in
103           that Notify and exposures etc can be selected on it at that time to
104           know when to draw, unless perhaps a background pixel or pixmap in
105           this "MitScreenSaverSetAttributes()" is enough.
106
107           Only one client at a time can setup a saver window like this.  If
108           another has done so then an "Access" error results.
109
110       "$X->MitScreenSaverUnsetAttributes ($drawable)"
111           Unset the screen saver window.  If the client did not set the
112           window then do nothing.
113
114           This changes the saver from "External" kind back to the server
115           builtin.  If the screen saver is currently active then that happens
116           immediately.
117
118           At client shutdown an Unset is done automatically, unless
119           "RetainPermanent" closedown mode.
120

EVENTS

122       "MitScreenSaverNotify" events are sent to the client when selected by
123       "MitScreenSaverSelectInput()" above.  These events report when the
124       screen saver state changes.  The event has the usual fields
125
126           name             "MitScreenSaverNotify"
127           synthetic        true if from a SendEvent
128           code             integer opcode
129           sequence_number  integer
130
131       and event-specific fields
132
133           state         "Off", "On", "Cycle"
134           time          server timestamp (integer)
135           root          root window of affected screen (XID)
136           window        the screen saver window (XID)
137           kind          "Blanked", "Internal", "External"
138           forced        integer 0 or 1
139
140       "state" is "Off" if the saver has turned off or "On" if it turned on.
141       "forced" is 1 if the change was due to a "ForceScreenSaver()" request
142       rather than user activity/inactivity.  On/Off events are selected by
143       NotifyMask to "MitScreenSaverSelectInput()" above.
144
145       "state" is "Cycle" if the saver cycling period has expired, which means
146       it's time to show something different.  This is selected by CycleMask
147       to "MitScreenSaverSelectInput()" above.
148
149       "kind" is the current saver kind per "MitScreenSaverKind" below.
150

ENUM TYPES

152       The following types are available for "$X->interp()" and "$X->num()"
153       after "init_extension()".
154
155       MitScreenSaverKind
156               "Blanked"    0     video output turned off
157               "Internal"   1     server builtin saver
158               "External"   2     external saver client
159
160       MitScreenSaverState
161           The state of the screen saver, as returned by
162           "MitScreenSaverQueryInfo()" and in "MitScreenSaverNotify" events.
163
164               "Off"         0
165               "On"          1
166               "Cycle"       2
167               "Disabled"    3
168
169       For example,
170
171           my $num = $X->num("MitScreenSaverKind", "External");
172           # sets $num to 2
173

BUGS

175       In XFree86 and X.org servers through to circa X.org 1.10, if the screen
176       saver is activated with a "ForceScreenSaver()" request then the
177       $til_or_since from "MitScreenSaverQueryInfo()" is a big number,
178       apparently being a negative for the future time when it would have
179       activated due to idle.  There's no attempt to do anything about that
180       here.
181
182       Also in these servers when the saver is "On" the idle timeout
183       apparently continues to fire too, so the "since" of $til_or_since is
184       only since the last firing, as if screen saver was re-activated, not
185       the time since first activated, or something like that.
186

HOME PAGE

198       <http://user42.tuxfamily.org/x11-protocol-other/index.html>
199

LICENSE

201       Copyright 2011, 2012, 2013, 2014, 2016, 2017 Kevin Ryde
202
203       X11-Protocol-Other is free software; you can redistribute it and/or
204       modify it under the terms of the GNU General Public License as
205       published by the Free Software Foundation; either version 3, or (at
206       your option) any later version.
207
208       X11-Protocol-Other is distributed in the hope that it will be useful,
209       but WITHOUT ANY WARRANTY; without even the implied warranty of
210       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
211       General Public License for more details.
212
213       You should have received a copy of the GNU General Public License along
214       with X11-Protocol-Other.  If not, see <http://www.gnu.org/licenses/>.
215
216
217
218perl v5.30.1                      2020-0X11-13:0:Protocol::Ext::MIT_SCREEN_SAVER(3)