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 ALSOXSetScreenSaver(3x)xset(1)X Version 11 Release 5 XHPSSChangeNotify(3X)
