manpagez: man pages & more
man X11::Protocol::Ext::MIT_SCREEN_SAVER(3)
Home | html | info | man
X11::Protocol::Ext::MIT_SCREEN_SAVER(3)



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 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(3), X11::Protocol::Ext::DPMS(3)

       /usr/share/doc/x11proto-scrnsaver-dev/saver.txt.gz

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

       xscreensaver(1), xssstate(1), xprintidle(1), X11::IdleTime


HOME PAGE

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


LICENSE

       Copyright 2011, 2012, 2013, 2014, 2016, 2017 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/>.




perl v5.28.1                      2017-X11::Protocol::Ext::MIT_SCREEN_SAVER(3)

x11-protocol-other 30 - Generated Tue Feb 19 07:20:41 CST 2019
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.