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)