461 lines
15 KiB
HTML
461 lines
15 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of XScreenSaver</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>XScreenSaver</H1>
|
|
Section: C Library Functions (3)<BR>Updated: libXScrnSaver 1.2.3<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
XScreenSaver - X11 Screen Saver extension client library
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>#include <<A HREF="file:///usr/include/X11/extensions/scrnsaver.h">X11/extensions/scrnsaver.h</A>></B>
|
|
|
|
<P>
|
|
|
|
<PRE>
|
|
|
|
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 eventMask; /* events */
|
|
<BR>
|
|
} 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 */
|
|
<BR>
|
|
} XScreenSaverNotifyEvent;
|
|
</PRE>
|
|
|
|
<DL COMPACT>
|
|
<DT id="1">
|
|
<DD>Bool XScreenSaverQueryExtension(Display *<I>dpy</I>,
|
|
int *<I>event_base_return</I>, int *<I>error_base_return</I>);
|
|
<DT id="2">
|
|
<DD>Status XScreenSaverQueryVersion(Display *<I>dpy</I>,
|
|
int *<I>major_version_return</I>, int *<I>minor_version_return</I>);
|
|
<DT id="3">
|
|
<DD>XScreenSaverInfo *XScreenSaverAllocInfo(void);
|
|
<DT id="4">
|
|
<DD>Status XScreenSaverQueryInfo(Display *<I>dpy</I>, Drawable <I>drawable</I>,
|
|
XScreenSaverInfo *<I>saver_info</I>);
|
|
<DT id="5">
|
|
<DD>void XScreenSaverSelectInput(Display *<I>dpy</I>, Drawable <I>drawable</I>,
|
|
unsigned long <I>mask</I>);
|
|
<DT id="6">
|
|
<DD>void XScreenSaverSetAttributes(Display *<I>dpy</I>, Drawable <I>drawable</I>,
|
|
int <I>x</I>,
|
|
int <I>y</I>,
|
|
unsigned int <I>width</I>,
|
|
unsigned int <I>height</I>,
|
|
unsigned int <I>border_width</I>,
|
|
int <I>depth</I>,
|
|
unsigned int <I>class</I>,
|
|
Visual *<I>visual</I>,
|
|
unsigned long <I>valuemask</I>,
|
|
XSetWindowAttributes *<I>attributes</I>);
|
|
<DT id="7">
|
|
<DD>void XScreenSaverUnsetAttributes(Display *<I>dpy</I>,
|
|
Drawable <I>drawable</I>);
|
|
<DT id="8">
|
|
<DD>void XScreenSaverRegister(Display *<I>dpy</I>, int <I>screen</I>,
|
|
XID <I>xid</I>, Atom <I>type</I>);
|
|
<DT id="9">
|
|
<DD>Status XScreenSaverUnregister(Display *<I>dpy</I>, int <I>screen</I>);
|
|
<DT id="10">
|
|
<DD>Status XScreenSaverGetRegistered(Display *<I>dpy</I>, int <I>screen</I>,
|
|
XID *<I>xid</I>, Atom *<I>type</I>);
|
|
<DT id="11">
|
|
<DD>void XScreenSaverSuspend(Display *<I>dpy</I>, Bool <I>suspend</I>);
|
|
</DL>
|
|
<P>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
The X Window System provides support for changing the image on a
|
|
display screen after a user-settable period of inactivity to avoid
|
|
burning the cathode ray tube phosphors.
|
|
However, 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.
|
|
<P>
|
|
|
|
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 capabilities 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 extension provides a means for writing such clients.
|
|
<A NAME="lbAE"> </A>
|
|
<H3>Assumptions</H3>
|
|
|
|
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 <I>override-redirect</I> 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
|
|
<B>QueryTree</B> requests on the root window, so it is typically not
|
|
visible to other clients.
|
|
<P>
|
|
|
|
<B>XScreenSaverQueryExtension</B>
|
|
|
|
returns
|
|
<B>True</B>
|
|
|
|
if the
|
|
<I>XScreenSaver</I>
|
|
|
|
extension is available on the given display.
|
|
A client must call
|
|
<B>XScreenSaverQueryExtension</B>
|
|
|
|
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).
|
|
<P>
|
|
|
|
If the extension is supported, the event number for
|
|
<I>ScreenSaverNotify</I>
|
|
|
|
events is returned in the value pointed to by <I>event_base</I>.
|
|
Since no additional errors are defined by this extension, the results
|
|
of <I>error_base</I> are not defined.
|
|
<P>
|
|
|
|
<B>XScreenSaverQueryVersion</B>
|
|
|
|
returns
|
|
<B>True</B>
|
|
|
|
if the request succeeded; the values of the major and minor protocol
|
|
versions supported by the server are returned in
|
|
<I>major_version_return</I>
|
|
|
|
and
|
|
<I>minor_version_return .</I>
|
|
|
|
<P>
|
|
|
|
<B>XScreenSaverAllocInfo</B>
|
|
|
|
allocates and returns an <B>XScreenSaverInfo</B> structure
|
|
for use in calls to <B>XScreenSaverQueryInfo</B>.
|
|
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 <I>XFree</I>.
|
|
<P>
|
|
|
|
<B>XScreenSaverQueryInfo</B>
|
|
|
|
returns information about the current state of the
|
|
screen server in <I>saver_info</I> and a non-zero value is
|
|
returned.
|
|
If the extension is not supported, <I>saver_info</I> is not changed and 0
|
|
is returned.
|
|
<P>
|
|
|
|
The <I>state</I> field specifies whether or not the screen saver is currently
|
|
active and how the <I>til-or-since</I> value should be interpreted:
|
|
<DL COMPACT>
|
|
<DT id="12"><I>Off</I>
|
|
|
|
<DD>
|
|
The screen is not currently being saved; <I>til-or-since</I>
|
|
specifies the number of milliseconds until the screen saver is expected to
|
|
activate.
|
|
<DT id="13"><I>On</I>
|
|
|
|
<DD>
|
|
The screen is currently being saved; <I>til-or-since</I> specifies
|
|
the number of milliseconds since the screen saver activated.
|
|
<DT id="14"><I>Disabled</I>
|
|
|
|
<DD>
|
|
The screen saver is currently disabled; <I>til-or-since</I> is zero.
|
|
</DL>
|
|
<P>
|
|
|
|
The <I>kind</I> field specifies the mechanism that either is currently being
|
|
used or would have been were the screen being saved:
|
|
<DL COMPACT>
|
|
<DT id="15"><I>Blanked</I>
|
|
|
|
<DD>
|
|
The video signal to the display monitor was disabled.
|
|
<DT id="16"><I>Internal</I>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="17"><I>External</I>
|
|
|
|
<DD>
|
|
The screen saver window was mapped with attributes set by a
|
|
client using the <B>ScreenSaverSetAttributes</B> request.
|
|
</DL>
|
|
<P>
|
|
|
|
The <I>idle</I> field specifies the number of milliseconds since the last
|
|
input was received from the user on any of the input devices.
|
|
<BR>
|
|
|
|
The <I>event-mask</I> field specifies which, if any, screen saver
|
|
events this client has requested using <B>ScreenSaverSelectInput</B>.
|
|
<P>
|
|
|
|
<B>XScreenSaverSelectInput</B>
|
|
|
|
asks that events related to
|
|
the screen saver be generated for this client.
|
|
If
|
|
no bits are set in <I>event-mask</I>, then no events will be generated.
|
|
Otherwise, any combination of the following bits may be set:
|
|
<DL COMPACT>
|
|
<DT id="18"><B>ScreenSaverNotify</B>
|
|
|
|
<DD>
|
|
If this bit is set, <B>ScreenSaverNotify</B> events are generated whenever
|
|
the screen saver is activated or deactivated.
|
|
<DT id="19"><B>ScreenSaverCycle</B>
|
|
|
|
<DD>
|
|
If this bit is set, <B>ScreenSaverNotify</B> events are generated whenever
|
|
the screen saver cycle interval passes.
|
|
</DL>
|
|
<P>
|
|
|
|
<B>XScreenSaverSetAttributes</B>
|
|
|
|
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.
|
|
<BR>
|
|
|
|
Otherwise, the specified window attributes are checked as if
|
|
they were used in a core <B>CreateWindow</B> request whose
|
|
parent is the root.
|
|
The <I>override-redirect</I> field is ignored as it is implicitly set
|
|
to True.
|
|
If the window attributes result in an error according to the rules for
|
|
<B>CreateWindow</B>, the request is ignored.
|
|
<BR>
|
|
|
|
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
|
|
<I>background-pixmap</I> or <I>cursor</I> attributes may be
|
|
freed immediately.
|
|
The server is free to copy the <I>background-pixmap</I> or <I>cursor</I>
|
|
resources or to use them in place; therefore, the effect of changing
|
|
the contents of those resources is undefined.
|
|
If the specified <I>colormap</I> 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.
|
|
<BR>
|
|
|
|
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.
|
|
<BR>
|
|
|
|
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 <B>ForceScreenSaver</B> request with
|
|
a value of Reset, or any request that would cause the window to be
|
|
unmapped.
|
|
<BR>
|
|
|
|
If the screen saver activates while the server is grabbed by another
|
|
client, the internal saver mechanism is used.
|
|
The <B>ForceScreenSaver</B> request may be used with a value of Active
|
|
to deactivate the internal saver and activate the external saver.
|
|
<BR>
|
|
|
|
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 RetainTemporary, the current screen saver
|
|
is deactivated and the internal screen saver is immediately activated.
|
|
<BR>
|
|
|
|
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.
|
|
<BR>
|
|
|
|
When the screen saver is being deactivated and then immediately
|
|
reactivated (such as when switching screen savers), the server
|
|
may leave the screen saver window mapped (typically to avoid
|
|
generating exposures).
|
|
<P>
|
|
|
|
<B>XScreenSaverUnsetAttributes</B>
|
|
|
|
instructs the server to discard
|
|
any previous screen saver window attributes set by this client.
|
|
<P>
|
|
|
|
<B>XScreenSaverRegister</B>
|
|
|
|
stores the given <I>XID</I> in the <B>_SCREEN_SAVER_ID</B>
|
|
property (of the given <I>type</I>) on the
|
|
root window of the specified <I>screen</I>.
|
|
It returns zero if an error is encountered and the property is not
|
|
changed, otherwise it returns non-zero.
|
|
<P>
|
|
|
|
<B>XScreenSaverUnregister</B>
|
|
|
|
removes any <B>_SCREEN_SAVER_ID</B> from the
|
|
root window of the specified <I>screen</I>.
|
|
It returns zero if an error is encountered and the property is
|
|
changed, otherwise it returns non-zero.
|
|
<P>
|
|
|
|
<B>XScreenSaverGetRegistered</B>
|
|
|
|
returns the <I>XID</I> and <I>type</I> stored in
|
|
the <B>_SCREEN_SAVER_ID</B> property on the
|
|
root window of the specified <I>screen</I>.
|
|
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.
|
|
<P>
|
|
|
|
<B>XScreenSaverSuspend</B>
|
|
|
|
temporarily suspends the screensaver and DPMS timer if <I>suspend</I>
|
|
is 'True', and restarts the timer if <I>suspend</I> is 'False'.
|
|
<BR>
|
|
|
|
This function should be used by applications that don't want the
|
|
screensaver or DPMS to become activated while they're for example in
|
|
the process of playing a media sequence, or are otherwise continuously
|
|
presenting visual information to the user while in a non-interactive
|
|
state. This function is not intended to be called by an external
|
|
screensaver application.
|
|
<BR>
|
|
|
|
If <B>XScreenSaverSuspend</B> is called multiple times with <I>suspend</I>
|
|
set to 'True', it must be called an equal number of times with
|
|
<I>suspend</I> set to 'False' in order for the screensaver timer to be
|
|
restarted. This request has no affect if a client tries to resume the
|
|
screensaver without first having suspended it.
|
|
<B>XScreenSaverSuspend</B> can thus not be used by one client to resume
|
|
the screensaver if it's been suspended by another client.
|
|
<BR>
|
|
|
|
If a client that has suspended the screensaver becomes disconnected from
|
|
the X server, the screensaver timer will automatically be restarted, unless
|
|
it's still suspended by another client. Suspending the screensaver timer
|
|
doesn't prevent the screensaver from being forceably activated with the
|
|
<B>ForceScreenSaver</B> request, or a DPMS mode from being set with the
|
|
<B>DPMSForceLevel</B> request.
|
|
<BR>
|
|
|
|
<B>XScreenSaverSuspend</B> also doesn't deactivate the screensaver or DPMS
|
|
if either is active at the time the request to suspend them is received by
|
|
the X server. But once they've been deactivated, they won't automatically
|
|
be activated again, until the client has canceled the suspension.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>ERRORS</H2>
|
|
|
|
<B>XScreenSaverSelectInput,</B>
|
|
|
|
<B>XScreenSaverQueryInfo,</B>
|
|
|
|
<B>XScreenSaverSetAttributes</B>
|
|
|
|
and
|
|
<B>XScreenSaverUnsetAttributes</B>
|
|
|
|
will generate a
|
|
<I>BadDrawable</I>
|
|
|
|
error if <I>drawable</I> is not a valid drawable identifier.
|
|
If any undefined bits are set in <I>event-mask</I>,
|
|
a BadValue error is generated by
|
|
<B>XScreenSaverSelectInput .</B>
|
|
|
|
<P>
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H2>AVAILABILITY</H2>
|
|
|
|
<B>XScreenSaverSuspend</B> is available in version 1.1 and later versions
|
|
of the X Screen Saver Extension. Version 1.1 was first released with
|
|
X11R7.1.
|
|
<P>
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<A HREF="/cgi-bin/man/man2html?7+X">X</A>(7)
|
|
<A NAME="lbAI"> </A>
|
|
<H2>AUTHORS</H2>
|
|
|
|
Jim Fulton and Keith Packard.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>STABILITY</H2>
|
|
|
|
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.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="20"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="21"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="22"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="23"><A HREF="#lbAE">Assumptions</A><DD>
|
|
</DL>
|
|
<DT id="24"><A HREF="#lbAF">ERRORS</A><DD>
|
|
<DT id="25"><A HREF="#lbAG">AVAILABILITY</A><DD>
|
|
<DT id="26"><A HREF="#lbAH">SEE ALSO</A><DD>
|
|
<DT id="27"><A HREF="#lbAI">AUTHORS</A><DD>
|
|
<DT id="28"><A HREF="#lbAJ">STABILITY</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:06:01 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|