man/Xss.man

   1 .\"
   2 .\" Copyright (C) 2003 The XFree86 Project, Inc.  All Rights Reserved.
   3 .\"
   4 .\" Permission is hereby granted, free of charge, to any person obtaining
   5 .\" a copy of this software and associated documentation files (the
   6 .\" "Software"), to deal in the Software without restriction, including
   7 .\" without limitation the rights to use, copy, modify, merge, publish,
   8 .\" distribute, sublicense, and/or sell copies of the Software, and to
   9 .\" permit persons to whom the Software is furnished to do so, subject to
  10 .\" the following conditions:
  11 .\"
  12 .\" The above copyright notice and this permission notice shall be
  13 .\" included in all copies or substantial portions of the Software.
  14 .\"
  15 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  16 .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  17 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
  18 .\" IN NO EVENT SHALL THE XFREE86 PROJECT BE LIABLE FOR ANY CLAIM, DAMAGES
  19 .\" OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
  20 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
  21 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  22 .\"
  23 .\" Except as contained in this notice, the name of the XFree86 Project
  24 .\" shall not be used in advertising or otherwise to promote the sale, use
  25 .\" or other dealings in this Software without prior written authorization
  26 .\" from the XFree86 Project.
  27 .\"
  28 .TH XScreenSaver __libmansuffix__ __vendorversion__
  29 .SH NAME
  30 XScreenSaver \- X11 Screen Saver extension client library
  31 .SH SYNOPSIS
  32 .B #include <X11/extensions/scrnsaver.h>
  33 .PP
  34 .nf
  35 .ta .5i 2i
  36 typedef struct {
  37     Window window;                /\(** screen saver window */
  38     int state;                    /\(** ScreenSaver{Off,On,Disabled} */
  39     int kind;                     /\(** ScreenSaver{Blanked,Internal,External} */
  40     unsigned long til_or_since;   /\(** milliseconds */
  41     unsigned long idle;           /\(** milliseconds */
  42     unsigned long eventMask;      /\(** events */
  43 .br
  44 } XScreenSaverInfo;
  45
  46 typedef struct {
  47     int type;               /\(** of event */
  48     unsigned long serial;   /\(** # of last request processed by server */
  49     Bool send_event;        /\(** true if this came frome a SendEvent request */
  50     Display *display;       /\(** Display the event was read from */
  51     Window window;          /\(** screen saver window */
  52     Window root;            /\(** root window of event screen */
  53     int state;              /\(** ScreenSaver{Off,On,Cycle} */
  54     int kind;               /\(** ScreenSaver{Blanked,Internal,External} */
  55     Bool forced;            /\(** extents of new region */
  56     Time time;              /\(** event timestamp */
  57 .br
  58 } XScreenSaverNotifyEvent;
  59 .fi
  60 .HP
  61 Bool XScreenSaverQueryExtension(Display *\fIdpy\fP,
  62 int *\fIevent_base_return\fP, int *\fIerror_base_return\fP\^);
  63 .HP
  64 Status XScreenSaverQueryVersion(Display *\fIdpy\fP,
  65 int *\fImajor_version_return\fP, int *\fIminor_version_return\fP\^);
  66 .HP
  67 XScreenSaverInfo *XScreenSaverAllocInfo(\^void\^);
  68 .HP
  69 Status XScreenSaverQueryInfo(\^Display *\fIdpy\fP, Drawable \fIdrawable\fP,
  70 XScreenSaverInfo *\fIsaver_info\fP\^);
  71 .HP
  72 void XScreenSaverSelectInput(Display *\fIdpy\fP, Drawable \fIdrawable\fP,
  73 unsigned long \fImask\fp\^);
  74 .HP
  75 void XScreenSaverSetAttributes(Display *\fIdpy\fP, Drawable \fIdrawable\fP,
  76 int \fIx\fP,
  77 int \fIy\fP,
  78 unsigned int \fIwidth\fP,
  79 unsigned int \fIheight\fP,
  80 unsigned int \fIborder_width\fP,
  81 int \fIdepth\fP,
  82 unsigned int \fIclass\fP,
  83 Visual *\fIvisual\fP,
  84 unsigned long \fIvaluemask\fP,
  85 XSetWindowAttributes *\fIattributes\fP\^);
  86 .HP
  87 void XScreenSaverUnsetAttributes(Display *\fIdpy\fP,
  88 Drawable \fIdrawable\fP\^);
  89 .HP
  90 void XScreenSaverSaverRegister(Display *\fIdpy\fP, int \fIscreen\fP,
  91 XID \fIxid\fP, Atom \fItype\fP\^);
  92 .HP
  93 Status XScreenSaverUnregister(Display *\fIdpy\fP, int \fIscreen\fP\^);
  94 .HP
  95 Status XScreenSaverGetRegistered(Display *\fIdpy\fP, int \fIscreen\fP,
  96 XID *\fIxid\fP, Atom *\fItype\fP\^);
  97 .HP
  98 void XScreenSaverSuspend(Display *\fIdpy\fP, Bool \fIsuspend\fP\^);
  99 .PP
 100 .SH DESCRIPTION
 101 The X Window System provides support for changing the image on a
 102 display screen after a user-settable period of inactivity to avoid
 103 burning the cathode ray tube phosphors.
 104 However, no interfaces are provided for the user to control the image
 105 that is drawn.
 106 This extension allows an external ``screen saver'' client to detect
 107 when the alternate image is to be displayed and to provide the
 108 graphics.
 109 .PP
 110 Current X server implementations typically provide at least one form of
 111 ``screen saver'' image.
 112 Historically, this has been a copy of the X logo drawn against the
 113 root background pattern.
 114 However, many users have asked for the mechanism to allow them to
 115 write screen saver programs that provide capabilities similar to those
 116 provided by other window systems.
 117 In particular, such users often wish to be able to display corporate
 118 logos, instructions on how to reactivate the screen, and automatic
 119 screen-locking utilities.
 120 This extension provides a means for writing such clients.
 121 .SS Assumptions
 122 This extension exports the notion of a special screen saver window that is
 123 mapped above all other windows on a display.
 124 This window has the \fIoverride-redirect\fP attribute set so that it
 125 is not subject to manipulation by the window manager.
 126 Furthermore, the X identifier for the window is never returned by
 127 \fBQueryTree\fP requests on the root window, so it is typically not
 128 visible to other clients.
 129 .PP
 130 .B XScreenSaverQueryExtension
 131 returns
 132 .B True
 133 if the
 134 .I XScreenSaver
 135 extension is available on the given display.
 136 A client must call
 137 .B XScreenSaverQueryExtension
 138 before calling any other XScreenSaver function in order
 139 to negotiate a compatible protocol version; otherwise the client will
 140 get undefined behavior (XScreenSaver may or may not work).
 141 .PP
 142 If the extension is supported, the event number for
 143 .I ScreenSaverNotify
 144 events is returned in the value pointed to by \fIevent_base\fP.
 145 Since no additional errors are defined by this extension, the results
 146 of \fIerror_base\fP are not defined.
 147 .PP
 148 .B XScreenSaverQueryVersion
 149 returns
 150 .B True
 151 if the request succeeded; the values of the major and minor protocol
 152 versions supported by the server are returned in
 153 .I major_version_return
 154 and
 155 .I minor_version_return .
 156 .PP
 157 .B XScreenSaverAllocInfo
 158 allocates and returns an \fBXScreenSaverInfo\fP structure
 159 for use in calls to \fBXScreenSaverQueryInfo\fP.
 160 All fields in the structure are initialized to zero.
 161 If insufficient memory is available, NULL is returned.
 162 The results of this routine can be released using \fIXFree\fP.
 163 .PP
 164 .B XScreenSaverQueryInfo
 165 returns information about the current state of the
 166 screen server in \fIsaver_info\fP and a non-zero value is
 167 returned.
 168 If the extension is not supported, \fIsaver_info\fP is not changed and 0
 169 is returned.
 170 .PP
 171 The \fIstate\fP field specifies whether or not the screen saver is currently
 172 active and how the \fItil-or-since\fP value should be interpreted:
 173 .TP 4
 174 .I Off
 175 The screen is not currently being saved; \fItil-or-since\fP
 176 specifies the number of milliseconds until the screen saver is expected to
 177 activate.
 178 .TP 4
 179 .I On
 180 The screen is currently being saved; \fItil-or-since\fP specifies
 181 the number of milliseconds since the screen saver activated.
 182 .TP 4
 183 .I Disabled
 184 The screen saver is currently disabled; \fItil-or-since\fP is zero.
 185 .PP
 186 The \fIkind\fP field specifies the mechanism that either is currently being
 187 used or would have been were the screen being saved:
 188 .TP 4
 189 .I Blanked
 190 The video signal to the display monitor was disabled.
 191 .TP 4
 192 .I Internal
 193 A server-dependent, built-in screen saver image was displayed; either no
 194 client had set the screen saver window attributes or a different client
 195 had the server grabbed when the screen saver activated.
 196 .TP 4
 197 .I External
 198 The screen saver window was mapped with attributes set by a
 199 client using the \fBScreenSaverSetAttributes\fP request.
 200 .PP
 201 The \fIidle\fP field specifies the number of milliseconds since the last
 202 input was received from the user on any of the input devices.
 203 .br
 204 The \fIevent-mask\fP field specifies which, if any, screen saver
 205 events this client has requested using \fBScreenSaverSelectInput\fP.
 206 .PP
 207 .B XScreenSaverSelectInput
 208 asks that events related to
 209 the screen saver be generated for this client.
 210 If
 211 no bits are set in \fIevent-mask\fP, then no events will be generated.
 212 Otherwise, any combination of the following bits may be set:
 213 .TP 8
 214 .B ScreenSaverNotify
 215 If this bit is set, \fBScreenSaverNotify\fP events are generated whenever
 216 the screen saver is activated or deactivated.
 217 .TP 8
 218 .B ScreenSaverCycle
 219 If this bit is set, \fBScreenSaverNotify\fP events are generated whenever
 220 the screen saver cycle interval passes.
 221 .PP
 222 .B XScreenSaverSetAttributes
 223 sets the attributes to be used
 224 the next time the external screen saver is activated.
 225 If another client currently has the attributes set,
 226 a BadAccess error is generated and the request is ignored.
 227 .br
 228 Otherwise, the specified window attributes are checked as if
 229 they were used in a core \fBCreateWindow\fP request whose
 230 parent is the root.
 231 The \fIoverride-redirect\fP field is ignored as it is implicitly set
 232 to True.
 233 If the window attributes result in an error according to the rules for
 234 \fBCreateWindow\fP, the request is ignored.
 235 .br
 236 Otherwise, the attributes are stored and will take effect on the next
 237 activation that occurs when the server is not grabbed by another client.
 238 Any resources specified for the
 239 \fIbackground-pixmap\fP or \fIcursor\fP attributes may be
 240 freed immediately.
 241 The server is free to copy the \fIbackground-pixmap\fP or \fIcursor\fP
 242 resources or to use them in place; therefore, the effect of changing
 243 the contents of those resources is undefined.
 244 If the specified \fIcolormap\fP no longer exists when the screen saver
 245 activates, the parent's colormap is used instead.
 246 If no errors are generated by this request, any previous screen saver
 247 window attributes set by this client are released.
 248 .br
 249 When the screen saver next activates and the server is not grabbed by
 250 another client, the screen saver window is
 251 created, if necessary, and set to the specified attributes and events
 252 are generated as usual.
 253 The colormap associated with the screen saver window is installed.
 254 Finally, the screen saver window is mapped.
 255 .br
 256 The window remains mapped and at the top of the stacking order
 257 until the screen saver is deactivated in response to activity on
 258 any of the user input devices, a \fBForceScreenSaver\fP request with
 259 a value of Reset, or any request that would cause the window to be
 260 unmapped.
 261 .br
 262 If the screen saver activates while the server is grabbed by another
 263 client, the internal saver mechanism is used.
 264 The \fBForceScreenSaver\fP request may be used with a value of Active
 265 to deactivate the internal saver and activate the external saver.
 266 .br
 267 If the screen saver client's connection to the server is broken
 268 while the screen saver is activated and the client's close down mode has not
 269 been RetainPermanent or RetainTemporary, the current screen saver
 270 is deactivated and the internal screen saver is immediately activated.
 271 .br
 272 When the screen saver deactivates, the screen saver window's colormap
 273 is uninstalled and the window is unmapped (except as described below).
 274 The screen saver XID is disassociated
 275 with the window and the server may, but is not required to,
 276 destroy the window along with any children.
 277 .br
 278 When the screen saver is being deactivated and then immediately
 279 reactivated (such as when switching screen savers), the server
 280 may leave the screen saver window mapped (typically to avoid
 281 generating exposures).
 282 .PP
 283 .B XScreenSaverUnsetAttributes
 284 instructs the server to discard
 285 any previous screen saver window attributes set by this client.
 286 .PP
 287 .B XScreenSaverRegister
 288 stores the given \fIXID\fP in the \fB_SCREEN_SAVER_ID\fP
 289 property (of the given \fItype\fP) on the
 290 root window of the specified \fIscreen\fP.
 291 It returns zero if an error is encountered and the property is not
 292 changed, otherwise it returns non-zero.
 293 .PP
 294 .B XScreenSaverUnregister
 295 removes any \fB_SCREEN_SAVER_ID\fP from the
 296 root window of the specified \fIscreen\fP.
 297 It returns zero if an error is encountered and the property is
 298 changed, otherwise it returns non-zero.
 299 .PP
 300 .B XScreenSaverGetRegistered
 301 returns the \fIXID\fP and \fItype\fP stored in
 302 the \fB_SCREEN_SAVER_ID\fP property on the
 303 root window of the specified \fIscreen\fP.
 304 It returns zero if an error is encountered or if the property does not
 305 exist or is not of the correct format; otherwise it returns non-zero.
 306 .PP
 307 .B XScreenSaverSuspend
 308 temporarily suspends the screensaver and DPMS timer if \fIsuspend\fP
 309 is 'True', and restarts the timer if \fIsuspend\fP is 'False'.
 310 .br
 311 This function should be used by applications that don't want the
 312 screensaver or DPMS to become activated while they're for example in
 313 the process of playing a media sequence, or are otherwise continuously
 314 presenting visual information to the user while in a non-interactive
 315 state. This function is not intended to be called by an external
 316 screensaver application.
 317 .br
 318 If \fBXScreenSaverSuspend\fP is called multiple times with \fIsuspend\fP
 319 set to 'True', it must be called an equal number of times with
 320 \fIsuspend\fP set to 'False' in order for the screensaver timer to be
 321 restarted. This request has no affect if a client tries to resume the
 322 screensaver without first having suspended it.
 323 \fBXScreenSaverSuspend\fP can thus not be used by one client to resume
 324 the screensaver if it's been suspended by another client.
 325 .br
 326 If a client that has suspended the screensaver becomes disconnected from
 327 the X server, the screensaver timer will automatically be restarted, unless
 328 it's still suspended by another client. Suspending the screensaver timer
 329 doesn't prevent the screensaver from being forceably activated with the
 330 \fBForceScreenSaver\fP request, or a DPMS mode from being set with the
 331 \fBDPMSForceLevel\fP request.
 332 .br
 333 \fBXScreenSaverSuspend\fP also doesn't deactivate the screensaver or DPMS
 334 if either is active at the time the request to suspend them is received by
 335 the X server. But once they've been deactivated, they won't automatically
 336 be activated again, until the client has canceled the suspension.
 337 .SH "ERRORS"
 338 .B XScreenSaverSelectInput,
 339 .B XScreenSaverQueryInfo,
 340 .B XScreenSaverSetAttributes
 341 and
 342 .B XScreenSaverUnsetAttributes
 343 will generate a
 344 .I BadDrawable
 345 error if \fIdrawable\fP is not a valid drawable identifier.
 346 If any undefined bits are set in \fIevent-mask\fP,
 347 a BadValue error is generated by
 348 .B XScreenSaverSelectInput .
 349 .PP
 350 .SH AVAILABILITY
 351 \fBXScreenSaverSuspend\fP is available in version 1.1 and later versions
 352 of the X Screen Saver Extension. Version 1.1 was first released with
 353 X11R7.1.
 354 .PP
 355 .SH "SEE ALSO"
 356 X(__miscmansuffix__)
 357 .SH AUTHORS
 358 Jim Fulton and Keith Packard.
 359 .SH STABILITY
 360 This API is considered as experimental.
 361 The Xss library major revision may be incremented whenever
 362 incompatible changes are done to the API without notice.
 363 Use with care.