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 with
21       MitScreenSaverSelectInput().  There can only be one external saver
22       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, saver
28       cycle period, and the "Blank" or "Internal" builtin saver styles.  See
29       the core ForceScreenSaver() to forcibly turn on the screen saver.
30

REQUESTS

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

EVENTS

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

ENUM TYPES

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

BUGS

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

HOME PAGE

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

LICENSE

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