#chapter Animation Primitives

Animation is not a typical application area for XPCE.  The development
background of the system never demanded much animation and the runtime
environment (Unix/X11 with symbolic languages) is not very suitable to
realise the real-time demands for animation.

For implementing animations, it is necessary to know a little about XPCE
and X11 repaint strategy.  In principle changes to PCE graphical objects
are not immediately reflected on this display.  For example, try to run
the following demo:

	?- send(new(P, picture), open),
	   send(P, display, new(B, box(100, 100))),
	   forall(between(0, 200, X),
		  send(B, x, X)).

After a while a window with a box displayed at (200, 0) will appear on
the screen.  No animation ...  There are two problems with this code.
First of all, after `send(new(P, picture), open)', a PCE window will be
created and a request will be put in the communication channel to the
X11 server.  This channal buffers input until PCE flushes all pending
output when waiting for the next event.  Next PCE displays the box and
moves the box in 1 pixel steps to the right.  PCE however will only
update the X-window when waiting for events.  So, PCE will first
execute the entire animation and then paint the final result when the
idle loop is entered.

The method `graphical ->flush' forces XPCE to flush modifications to
the X11 server *now*.  So, lets try

	?- send(new(P, picture), open),
	   send(P, display, new(B, box(100, 100))),
	   forall(between(0, 200, X),
		  (send(B, flush),
		   send(B, x, X))).

This still yields the same result as the previous try.  Why?  PCE
now actually requests X11 to create a window after the box has been
displayed on it.  But the X11 server runs asynchronous from PCE. 
PCE continues with the animation, while the X server creates the
window.  When done, it will request PCE to paint the contents of
the window.  PCE is finished long before the X server has created
the window *and*, PCE won't notice the repaint request as it is
not looking for events.  So, we have to wait till the X-server has
done its job.  In this case the `frame <-confirm'/`frame ->return'
mechanism solves our problem:

	?- send(new(P, picture), open),
	   get(P, frame, Frame),
	   send(Frame, send_method,
		send_method(mapped, vector(bool),
			    if(@arg1 == @on,
			       message(Frame, return, mapped)))),
	   get(Frame, confirm, _),

	   send(P, display, new(B, box(100, 100))),
	   forall(between(0, 200, X),
		  (send(B, flush),
		   send(B, x, X))).

Now, the `frame <-confirm' will flush output and process events from
the X-server until `frame ->return' is executed.  Class frame calls
`frame ->mapped' on itself when the frame is actually realised and
mapped on the X-screen.  This method is redefined to make the <-confirm
call return.  Thus, `frame <-confirm' will make PCE block and processing
events till the frame is opened on this display.

RELEVANT BEHAVIOUR

This chapter describes class timer to fire messages at regular
intervals.  Other relevant behaviour is:

	`graphical ->flush'		Repaint the graphical *now*
	`graphical ->synchronise'	->flush and process input
	`frame <-confirm'		Process input until ->return.

The `Kangaroo' demo contributed by Anja van der Hulst illustrates
animation.
#end chapter

#class timer
#end class