MirOS Manual: XScreenSaverAllocInfo(3), XScreenSaverGetRegistered(3), XScreenSaverQueryExtension(3), XScreenSaverQueryInfo(3), XScreenSaverQueryVersion(3), XScreenSaverRegister(3), XScreenSaverSelectInput(3), XScreenSaverSetAttributes(3), XScreenSaverUnregister(3), XScreenSaverUnsetAttributes(3), Xss(3)


XScreenSaver(3)     UNIX Programmer's Manual      XScreenSaver(3)

NAME

     XScreenSaver - X11 Screen Saver extension client library

SYNOPSIS

     #include <X11/extension/scrnsaver.h>

     typedef struct {
         Window window;                /* screen saver window */
         int state;                    /* ScreenSaver{Off,On,Disabled} */
         int kind;                     /* ScreenSaver{Blanked,Internal,External} */
         unsigned long til_or_since;   /* milliseconds */
         unsigned long idle;           /* milliseconds */
         unsigned long event_mask;     /* events */
     } XScreenSaverInfo;

     typedef struct {
         int type;               /* of event */
         unsigned long serial;   /* # of last request processed by server */
         Bool send_event;        /* true if this came frome a SendEvent request */
         Display *display;       /* Display the event was read from */
         Window window;          /* screen saver window */
         Window root;            /* root window of event screen */
         int state;              /* ScreenSaver{Off,On,Cycle} */
         int kind;               /* ScreenSaver{Blanked,Internal,External} */
         Bool forced;            /* extents of new region */
         Time time;              /* event timestamp */
     } XScreenSaverNotifyEvent;

     Bool XScreenSaverQueryExtension(Display *dpy, int
          *event_basep, int *error_basep);

     Status XScreenSaverQueryVersion(Display *dpy, int
          *major_versionp, int *minor_versionp);

     XScreenSaverInfo *XScreenSaverAllocInfo(void);

     Status XScreenSaverQueryInfo(Display *dpy, Drawable draw-
          able, XScreenSaverInfo *saver_info);

     void XScreenSaverSelectInput(Display *dpy, Drawable draw-
          able, unsigned long mask);

     void XScreenSaverSetAttributes(Display *dpy, Drawable draw-
          able, int x, int y, unsigned int width, unsigned int
          height, unsigned int border_width, int depth, unsigned
          int class, Visual *visual, unsigned long valuemask,
          XSetWindowAttributes *attributes);

     void XScreenSaverUnsetAttributes(Display *dpy, Drawable
          drawable);

XFree86                   Version 4.5.0                         1

XScreenSaver(3)     UNIX Programmer's Manual      XScreenSaver(3)

     void XScreenSaverSaverRegister(Display *dpy, int screen, XID
          xid, Atom type);

     Status XScreenSaverUnregister(Display *dpy, int screen);

     Status XScreenSaverGetRegistered(Display *dpy, int screen,
          XID *xid, Atom *type);

DESCRIPTION

     The X Window System provides support for changing the image
     on a display screen after a user-settable period of inac-
     tivity to avoid burning the cathode ray tube phosphors. How-
     ever, no interfaces are provided for the user to control the
     image that is drawn. This extension allows an external
     ``screen saver'' client to detect when the alternate image
     is to be displayed and to provide the graphics.

     Current X server implementations typically provide at least
     one form of ``screen saver'' image. Historically, this has
     been a copy of the X logo drawn against the root background
     pattern. However, many users have asked for the mechanism to
     allow them to write screen saver programs that provide capa-
     bilities similar to those provided by other window systems.
     In particular, such users often wish to be able to display
     corporate logos, instructions on how to reactivate the
     screen, and automatic screen-locking utilities. This exten-
     sion provides a means for writing such clients.

     Assumptions
     This extension exports the notion of a special screen saver
     window that is mapped above all other windows on a display.
     This window has the override-redirect attribute set so that
     it is not subject to manipulation by the window manager.
     Furthermore, the X identifier for the window is never
     returned by QueryTree requests on the root window, so it is
     typically not visible to other clients.

     XScreenSaverQueryExtension returns True if the XScreenSaver
     extension is available on the given display. A client must
     call XScreenSaverQueryExtension before calling any other
     XScreenSaver function in order to negotiate a compatible
     protocol version; otherwise the client will get undefined
     behavior (XScreenSaver may or may not work).

     If the extension is supported, the event number for Screen-
     SaverNotify events is returned in the value pointed to by
     event_base. Since no additional errors are defined by this
     extension, the results of error_base are not defined.

     XScreenSaverQueryVersion returns True if the request suc-
     ceeded; the values of the major and minor protocol versions
     supported by the server are returned in major_versionp and

XFree86                   Version 4.5.0                         2

XScreenSaver(3)     UNIX Programmer's Manual      XScreenSaver(3)

     minor_versionp .

     XScreenSaverAllocInfo allocates and returns an XScreenSaver-
     Info structure for use in calls to XScreenSaverQueryInfo.
     All fields in the structure are initialized to zero. If
     insufficient memory is available, NULL is returned. The
     results of this routine can be released using XFree.

     XScreenSaverQueryInfo returns information about the current
     state of the screen server in saver_info and a non-zero
     value is returned. If the extension is not supported,
     saver_info is not changed and 0 is returned.
     The state field specifies whether or not the screen saver is
     currently active and how the til-or-since value should be
     interpreted:

     Off The screen is not currently being saved; til-or-since
         specifies the number of milliseconds until the screen
         saver is expected to activate.

     On  The screen is currently being saved; til-or-since speci-
         fies the number of milliseconds since the screen saver
         activated.

     Disabled
         The screen saver is currently disabled; til-or-since is
         zero.
         The kind field specifies the mechanism that either is
         currently being used or would have been were the screen
         being saved:

     Blanked
         The video signal to the display monitor was disabled.

     Internal
         A server-dependent, built-in screen saver image was
         displayed; either no client had set the screen saver
         window attributes or a different client had the server
         grabbed when the screen saver activated.

     External
         The screen saver window was mapped with attributes set
         by a client using the ScreenSaverSetAttributes request.

     The idle field specifies the number of milliseconds since
     the last input was received from the user on any of the
     input devices.
     The event-mask field specifies which, if any, screen saver
     events this client has requested using ScreenSaverSelectIn-
     put.

XFree86                   Version 4.5.0                         3

XScreenSaver(3)     UNIX Programmer's Manual      XScreenSaver(3)

     XScreenSaverSelectInput asks that events related to the
     screen saver be generated for this client. If no bits are
     set in event-mask, then no events will be generated. Other-
     wise, any combination of the following bits may be set:

     ScreenSaverNotify
             If this bit is set, ScreenSaverNotify events are
             generated whenever the screen saver is activated or
             deactivated.

     ScreenSaverCycle
             If this bit is set, ScreenSaverNotify events are
             generated whenever the screen saver cycle interval
             passes.

     XScreenSaverSetAttributes sets the attributes to be used the
     next time the external screen saver is activated. If another
     client currently has the attributes set, a BadAccess error
     is generated and the request is ignored.
     Otherwise, the specified window attributes are checked as if
     they were used in a core CreateWindow request whose parent
     is the root. The override-redirect field is ignored as it is
     implicitly set to True. If the window attributes result in
     an error according to the rules for CreateWindow, the
     request is ignored.
     Otherwise, the attributes are stored and will take effect on
     the next activation that occurs when the server is not
     grabbed by another client. Any resources specified for the
     background-pixmap or cursor attributes may be freed immedi-
     ately. The server is free to copy the background-pixmap or
     cursor resources or to use them in place; therefore, the
     effect of changing the contents of those resources is unde-
     fined. If the specified colormap no longer exists when the
     screen saver activates, the parent's colormap is used
     instead. If no errors are generated by this request, any
     previous screen saver window attributes set by this client
     are released.
     When the screen saver next activates and the server is not
     grabbed by another client, the screen saver window is
     created, if necessary, and set to the specified attributes
     and events are generated as usual. The colormap associated
     with the screen saver window is installed. Finally, the
     screen saver window is mapped.
     The window remains mapped and at the top of the stacking
     order until the screen saver is deactivated in response to
     activity on any of the user input devices, a ForceScreen-
     Saver request with a value of Reset, or any request that
     would cause the window to be unmapped.
     If the screen saver activates while the server is grabbed by
     another client, the internal saver mechanism is used. The
     ForceScreenSaver request may be used with a value of Active
     to deactivate the internal saver and activate the external

XFree86                   Version 4.5.0                         4

XScreenSaver(3)     UNIX Programmer's Manual      XScreenSaver(3)

     saver.
     If the screen saver client's connection to the server is
     broken while the screen saver is activated and the client's
     close down mode has not been RetainPermanent or RetainTem-
     porary, the current screen saver is deactivated and the
     internal screen saver is immediately activated.
     When the screen saver deactivates, the screen saver window's
     colormap is uninstalled and the window is unmapped (except
     as described below). The screen saver XID is disassociated
     with the window and the server may, but is not required to,
     destroy the window along with any children.
     When the screen saver is being deactivated and then immedi-
     ately reactivated (such as when switching screen savers),
     the server may leave the screen saver window mapped (typi-
     cally to avoid generating exposures).

     XScreenSaverUnsetAttributes instructs the server to discard
     any previous screen saver window attributes set by this
     client.

     XScreenSaverRegister stores the given XID in the
     _SCREEN_SAVER_ID property (of the given type) on the root
     window of the specified screen. It returns zero if an error
     is encountered and the property is not changed, otherwise it
     returns non-zero.

     XScreenSaverUnregister removes any _SCREEN_SAVER_ID from the
     root window of the specified screen. It returns zero if an
     error is encountered and the property is changed, otherwise
     it returns non-zero.

     XScreenSaverGetRegistered returns the XID and type stored in
     the _SCREEN_SAVER_ID property on the root window of the
     specified screen. It returns zero if an error is encountered
     or if the property does not exist or is not of the correct
     format; otherwise it returns non-zero.

ERRORS

     XScreenSaverSelectInput, XScreenSaverQueryInfo, XScreen-
     SaverSetAttributes and XScreenSaverUnsetAttributes will gen-
     erate a BadDrawable error if drawable is not a valid draw-
     able identifier. If any undefined bits are set in event-
     mask, a BadValue error is generated by XScreenSaverSelectIn-
     put .

SEE ALSO

     Xlib(1), X(7)

AUTHORS

     Jim Fulton and Keith Packard.

XFree86                   Version 4.5.0                         5

XScreenSaver(3)     UNIX Programmer's Manual      XScreenSaver(3)

STABILITY

     This API is considered as experimental. The Xss library
     major revision may be incremented whenever incompatible
     changes are done to the API without notice. Use with care.

XFree86                   Version 4.5.0                         6

Generated on 2017-04-03 16:26:17 by $MirOS: src/scripts/roff2htm,v 1.88 2017/01/29 00:51:06 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002–2017 The MirOS Project, Germany.
This product includes material provided by mirabilos.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report — diffs preferred.