@begin(header)
author: ackerman=ag@ics.uci.edu
show_author: ShowNone
author_organization: MIT
node_expert: ackerman=ag@ics.uci.edu 
expiration_date: 10/10/93
last_modifier: ackerman=ag@ics.uci.edu
last_mod_date: 10/11/91
mod_num: 3
@end(header)
-------------
Expose Events
-------------

Expose events are generated whenever a window needs to be redrawn.  

---------------------------
Selecting for Expose Events
---------------------------

You get expose events by selecting for them with the XSelectInput
call:

     XSelectInput(display, w, event_mask)
           Display *display;
           Window w;
           long event_mask;

With certain exceptions, you will receive events only when you have
selected events for the window.  Again with certain exceptions, you
will receive no events for which you have not selected.

XSelectInput for expose events then takes:

	XSelectInput(the_display,the_window,ExposureMask);

where the_display and the_window have been created previously. 
The value ExposureMask can be found in the header file X.h
(usually in /usr/include/X11, but occasionally in
/usr/local/include/X11).

---------------------
Getting Expose Events
---------------------

You receive expose events in an XEvent structure.  See the
tutorial on using XEvents in code for more information on
how to use XEvents in your program.  

You will receive expose events in your event loop.  That is,
you will receive exposure events as the result of a
XNextEvent call.  You must then decide how to process
the expose event.

Note that you may receive more than 1 expose event for
a given window.  You may want to draw any graphics only
when the count field in the expose event structure is
0.  This is will be the last expose event in this
series.  For example:

	if (xevent.expose.count == 0)
		Draw_Some_Stuff(xevent.expose.window);


--------------------
When Do You Get More 
Than 1 Expose Event
--------------------

Say you have a window that is partially obscured by several
windows:


	-----------------------
	|			|
	|       #1		|
	|			|
     ------------	-------------	
     |   #2     |-------|     #3     |
     |          |       |            |
     ------------       --------------
    	
When window #1 is raised to the top, multiple expose events will be
generated for it.  Some applications wish to know that the region
previously obscured by window #2 needs to be refreshed separately
from the information that the region previously obscured by window
#3 needs to be refreshed.  Examples of applications that might need
this include architectural rendering packages that might find it
more costly to draw the entire image rather than individual regions.

----------------------
Avoiding Expose Events
----------------------

If your application finds it costly to draw on each expose event,
and you are drawing to a hardware platform with sufficient RAM,
you might want to consider backing store.  Backing store keeps
the image in a shadow area of server memory.  You ask for
backing store using the XChangeWindowAttributes.  The values
for backing_store can be Never, WhenMapped, and Always.  Note
that a server does not have to give your application backing
store, and you should be cautious in asking for it.  For example,
an application with 50 color images, each of which was 1000 pixels
by 1000 pixels (the size of a workstation screen) would require
50M of backing store.  In addition, no early servers (pre-R3,
still distributed by some vendors) do backing store.  Your
application should be prepared to handle expose events as normal,
and just use backing store to cut down the number of expose 
