XHPSSChangeNotify(3X) XHPSSChangeNotify(3X)
NAME
XHPSSChangeNotify - Allows applications to receive notification of screen saver state changes.
SYNOPSIS
#include <X11/XHPlib.h>
int XHPSSChangeNotify (display, ssHandle, flags)
Display *display;
Atom *ssHandle;
int flags;
ARGUMENTS
display Specifies the connection to the X server.
ssHandle Specifies a pointer to an atom, into which the X server will return a unique identifying screen saver id.
flags Specifies the bit mask that indicates the type of notifications the application wants to receive. The first bit
(bit 0) determines screen saver 'on' and 'off' states. The second bit (bit 1) indicates the 'draw' and 'cycle'
notification.
DESCRIPTION
These requests are part of an HP-proprietary extension to X. These requests allow one or more X clients to react to screen saver state
changes, such as locking the screen when the screen blanks or drawing patterns on the screen. To receive 'on' and 'off' messages, the
application only needs to call XHPSSChangeNotify(). To also receive 'draw' and 'cycle' messages, the application needs to call
XSetScreenSaver() as well as XHPSSChangeNotify().
To enable the screen saver, applications must first call XSetScreenSaver() and set the prefer_blanking to DontPreferBlanking. The X server
will not generate 'draw' and 'cycle' notification when blanking is turned on. The allow_exposures flag must be set to AllowExposures.
This ensures that proper notification will be sent out when it is safe to do drawing. This can also be done with "xset s noblank s
expose".
To begin receiving information on screen saver state changes, applications must use the XHPSSChangeNotify() function. Depending on how the
flags have been set, the screen saver program can receive notification of the following event_types:
XHP_SCREEN_SAVER_ON:
The screen saver timeout has initially expired. This is typically visually indicated by the screen blanking.
XHP_SCREEN_SAVER_OFF:
The screen saver has been reset, due to user input or mouse movement.
XHP_SCREEN_SAVER_DRAW:
The screen saver program can now draw into the screen saver window; the window id is supplied as part of the notification.
XHP_SCREEN_SAVER_CYCLE:
The cycle timeout has expired; this allows a screen saver program to modify (or animate) what it is displaying in the screen
saver window.
Caveat: Even if you enable bit 1, thus requesting 'draw' and
'cycle' notification, you will only receive these
*if* you had disabled blanking, using the calls described
earlier!
Once you have registered interest in screen saver notification, you will receive X events whose 'type' is set to 'ClientMessage', and whose
message type is the atom passed back by XHPSSChangeNotify(). For instance, the following event loop would detect and dispatch screen saver
events:
XEvent event;
for (;;)
{
XNextEvent (display &event);
if ((event.type == ClientMessage) &&
(event.xclient.message_type == ssHandle))
{
/* add code to dispatch screen saver event */
}
}
In the case of the XHP_SCREEN_SAVER_DRAW notification, you will also receive the window id for the screen saver window. This window id is
specified within the event.xclient.data.l[1] field and the event type is specified within event.xclient.data.l[0] field:
XClientMesssageEvent * message = (XClientMessageEvent *) &event;
event_type = message->data.l[0];
window = message->data.l[1];
EXAMPLES
This is a sequence of notification event_types a screen saver application might see:
Bit 1 off, or blanking enabled:
-------------------------------
XHP_SCREEN_SAVER_ON (When screen saver timeout expires)
XHP_SCREEN_SAVER_OFF (When input occurs or mouse is moved)
Bit 1 on, and blanking disabled:
--------------------------------
XHP_SCREEN_SAVER_ON (When screen saver timeout expires)
XHP_SCREEN_SAVER_DRAW (When it is safe to draw in the
specified window id)
XHP_SCREEN_SAVER_CYCLE (When screen saver cycle timeout
expires)
.
.
.
XHP_SCREEN_SAVER_CYCLE (When screen saver cycle timeout
expires)
XHP_SCREEN_SAVER_OFF (When input occurs or mouse is moved)
In the case that there are more than one screen attached to the X server, applications will receive screen saver events for each screen,
even screens that are not visible. Care should be taken to avoid rendering to a window using the wrong screen. To determine the screen,
use the following:
XGetWindowAttributes(display, event, window, &attr);
screenNum = XScreenNumberOfScreen(attr.screen);
CAUTION: An X error handler should be registered to catch attempts to draw to a non-existent window. The screen saver window is a special
window that is created and destroyed by the X Server. It is possible, in the case that a short timeout is defined, that the client may
issue draw requests to a window that has been destroyed before it completes all of its requests. If an error handler is not supplied, the
application will most likely terminate.
RETURN VALUE
This function returns 0 upon successful completion, -1 when the X Server is too old to support Screen Saver calls and 1 when too many
screen saver clients have already registered. There can be a maximum of 10 registered screen saver clients.
FILES
none
ORIGIN
Hewlett-Packard Company
SEE ALSO
XSetScreenSaver(3x)
xset(1)
X Version 11 Release 5 XHPSSChangeNotify(3X)