diff options
Diffstat (limited to 'man/Xss.man')
| -rw-r--r-- | man/Xss.man | 327 |
1 files changed, 327 insertions, 0 deletions
diff --git a/man/Xss.man b/man/Xss.man new file mode 100644 index 0000000..7d4eb2b --- /dev/null +++ b/man/Xss.man @@ -0,0 +1,327 @@ +.\" +.\" $XFree86: xc/lib/Xss/Xss.man,v 1.1 2003/10/26 19:00:24 herrb Exp $ +.\" +.\" Copyright (C) 2003 The XFree86 Project, Inc. All Rights Reserved. +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. +.\" IN NO EVENT SHALL THE XFREE86 PROJECT BE LIABLE FOR ANY CLAIM, DAMAGES +.\" OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the XFree86 Project +.\" shall not be used in advertising or otherwise to promote the sale, use +.\" or other dealings in this Software without prior written authorization +.\" from the XFree86 Project. +.\" +.TH XScreenSaver 3 __vendorversion__ +.SH NAME +XScreenSaver \- X11 Screen Saver extension client library +.SH SYNOPSIS +.B #include <X11/extension/scrnsaver.h> +.PP +.nf +.ta .5i 2i +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 */ +.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; +.fi +.HP +Bool XScreenSaverQueryExtension(Display *\fIdpy\fP, +int *\fIevent_basep\fP, int *\fIerror_basep\fP\^); +.HP +Status XScreenSaverQueryVersion(Display *\fIdpy\fP, int *\fImajor_versionp\fP, +int *\fIminor_versionp\fP\^); +.HP +XScreenSaverInfo *XScreenSaverAllocInfo(\^void\^); +.HP +Status XScreenSaverQueryInfo(\^Display *\fIdpy\fP, Drawable \fIdrawable\fP, +XScreenSaverInfo *\fIsaver_info\fP\^); +.HP +void XScreenSaverSelectInput(Display *\fIdpy\fP, Drawable \fIdrawable\fP, +unsigned long \fImask\fp\^); +.HP +void XScreenSaverSetAttributes(Display *\fIdpy\fP, Drawable \fIdrawable\fP, +int \fIx\fP, +int \fIy\fP, +unsigned int \fIwidth\fP, +unsigned int \fIheight\fP, +unsigned int \fIborder_width\fP, +int \fIdepth\fP, +unsigned int \fIclass\fP, +Visual *\fIvisual\fP, +unsigned long \fIvaluemask\fP, +XSetWindowAttributes *\fIattributes\fP\^); +.HP +void XScreenSaverUnsetAttributes(Display *\fIdpy\fP, +Drawable \fIdrawable\fP\^); +.HP +void XScreenSaverSaverRegister(Display *\fIdpy\fP, int \fIscreen\fP, +XID \fIxid\fP, Atom \fItype\fP\^); +.HP +Status XScreenSaverUnregister(Display *\fIdpy\fP, int \fIscreen\fP\^); +.HP +Status XScreenSaverGetRegistered(Display *\fIdpy\fP, int \fIscreen\fP, +XID *\fIxid\fP, Atom *\fItype\fP\^); +.PP +.SH DESCRIPTION +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. +.PP +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. +.SS 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 \fIoverride-redirect\fP 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 +\fBQueryTree\fP requests on the root window, so it is typically not +visible to other clients. +.PP +.B XScreenSaverQueryExtension +returns +.B True +if the +.I XScreenSaver +extension is available on the given display. +A client must call +.B 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). +.PP +If the extension is supported, the event number for +.I ScreenSaverNotify +events is returned in the value pointed to by \fIevent_base\fP. +Since no additional errors are defined by this extension, the results +of \fIerror_base\fP are not defined. +.PP +.B XScreenSaverQueryVersion +returns +.B True +if the request succeeded; the values of the major and minor protocol +versions supported by the server are returned in +.I major_versionp +and +.I minor_versionp . +.PP +.B XScreenSaverAllocInfo +allocates and returns an \fBXScreenSaverInfo\fP structure +for use in calls to \fBXScreenSaverQueryInfo\fP. +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 \fIXFree\fP. +.PP +.B XScreenSaverQueryInfo +returns information about the current state of the +screen server in \fIsaver_info\fP and a non-zero value is +returned. +If the extension is not supported, \fIsaver_info\fP is not changed and 0 +is returned. +.br +The \fIstate\fP field specifies whether or not the screen saver is currently +active and how the \fItil-or-since\fP value should be interpreted: +.TP 4 +.I Off +The screen is not currently being saved; \fItil-or-since\fP +specifies the number of milliseconds until the screen saver is expected to +activate. +.TP 4 +.I On +The screen is currently being saved; \fItil-or-since\fP specifies +the number of milliseconds since the screen saver activated. +.TP 4 +.I Disabled +The screen saver is currently disabled; \fItil-or-since\fP is zero. +.br +The \fIkind\fP field specifies the mechanism that either is currently being +used or would have been were the screen being saved: +.TP 4 +.I Blanked +The video signal to the display monitor was disabled. +.TP 4 +.I 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. +.TP 4 +.I External +The screen saver window was mapped with attributes set by a +client using the \fBScreenSaverSetAttributes\fP request. +.PP +The \fIidle\fP field specifies the number of milliseconds since the last +input was received from the user on any of the input devices. +.br +The \fIevent-mask\fP field specifies which, if any, screen saver +events this client has requested using \fBScreenSaverSelectInput\fP. +.PP +.B XScreenSaverSelectInput +asks that events related to +the screen saver be generated for this client. +If +no bits are set in \fIevent-mask\fP, then no events will be generated. +Otherwise, any combination of the following bits may be set: +.TP 8 +.B ScreenSaverNotify +If this bit is set, \fBScreenSaverNotify\fP events are generated whenever +the screen saver is activated or deactivated. +.TP 8 +.B ScreenSaverCycle +If this bit is set, \fBScreenSaverNotify\fP events are generated whenever +the screen saver cycle interval passes. +.PP +.B 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. +.br +Otherwise, the specified window attributes are checked as if +they were used in a core \fBCreateWindow\fP request whose +parent is the root. +The \fIoverride-redirect\fP field is ignored as it is implicitly set +to True. +If the window attributes result in an error according to the rules for +\fBCreateWindow\fP, 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 +\fIbackground-pixmap\fP or \fIcursor\fP attributes may be +freed immediately. +The server is free to copy the \fIbackground-pixmap\fP or \fIcursor\fP +resources or to use them in place; therefore, the effect of changing +the contents of those resources is undefined. +If the specified \fIcolormap\fP 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 \fBForceScreenSaver\fP 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 \fBForceScreenSaver\fP 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). +.PP +.B XScreenSaverUnsetAttributes +instructs the server to discard +any previous screen saver window attributes set by this client. +.PP +.B XScreenSaverRegister +stores the given \fIXID\fP in the \fB_SCREEN_SAVER_ID\fP +property (of the given \fItype\fP) on the +root window of the specified \fIscreen\fP. +It returns zero if an error is encountered and the property is not +changed, otherwise it returns non-zero. +.PP +.B XScreenSaverUnregister +removes any \fB_SCREEN_SAVER_ID\fP from the +root window of the specified \fIscreen\fP. +It returns zero if an error is encountered and the property is +changed, otherwise it returns non-zero. +.PP +.B XScreenSaverGetRegistered +returns the \fIXID\fP and \fItype\fP stored in +the \fB_SCREEN_SAVER_ID\fP property on the +root window of the specified \fIscreen\fP. +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. +.SH "ERRORS" +.B XScreenSaverSelectInput, +.B XScreenSaverQueryInfo, +.B XScreenSaverSetAttributes +and +.B XScreenSaverUnsetAttributes +will generate a +.I BadDrawable +error if \fIdrawable\fP is not a valid drawable identifier. +If any undefined bits are set in \fIevent-mask\fP, +a BadValue error is generated by +.B XScreenSaverSelectInput . +.PP +.SH "SEE ALSO" +Xlib(1), X(7) +.SH AUTHORS +Jim Fulton and Keith Packard. +.SH 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. |