pro pause,up=up,xcrs=xcrs,ycrs=ycrs,on_screen=on_screen
;+
; routine:        pause
;
; useage:         pause
;                 pause,up=up,xcrs=xcrs,ycrs=ycrs,on_screen=on_screen
;
; input:          none
;
; keyword input:  
;   up
;     if set, don't return until a upward button transition is
;     detected.  This is useful when pause is used between plots which
;     draw quickly.  Setting this keyword ensures that no plots are
;     skipped but also requires that each new plot be accompanied by a
;     downward and upward button transition.  The default is to skip
;     to the next plot as long a mouse button is pressed down.
;
;
; xcrs,ycrs
;     pixel location to put cursor while waiting
;
; on_screen
;     if set, don't pause if cursor not in plot window
;
; output:         none
;
; PURPOSE:
;     Momentarily stop execution until a mouse key is pressed.  While
;     in the paused state the cursor is changed to what looks like an
;     arrow pointing down on a button.  When any of the mouse buttons
;     are pressed the cursor returns to its original form and
;     execution continues.
;     
;     PAUSE will only interrupt execution if the output device is 'X'
;     and plot system variable !p.multi(0) eq 0.  The first condition
;     disables PAUSE when output is directed to a postscript file.
;     The second condition ensures that pauses occur only just before
;     the screen is erased for a new plot.
;     
;     NOTE: After PAUSE returns to the calling program different
;     actions can be performed depending on whether the left, middle
;     or right mouse button was pressed.  Just test on the !err system
;     variable: !err=1 => left !err=2 => middle !err=4 => right.
;
; COMMON BLOCKS: pause_blk
;                       
; EXAMPLE:        
;
;x=findgen(201)/10.-10. 
;for a=-2.,2.,.1 do begin & plot,x,1/(x^2*10.^a+1),tit=string(a) & pause & end
;
;for a=-2.,2.,.1 do begin & plot,x,1/(x^2*10.^a+1),tit=string(a) &$
;   pause,/u & end
;
;  author:  Paul Ricchiazzi                            22sep92
;           Institute for Computational Earth System Science
;           University of California, Santa Barbara
;-


if !d.name eq 'X' and !p.multi(0) eq 0 then begin
  cursor,xw,yw,/nowait,/device
  
  if xw eq -1 then begin
    if keyword_set(on_screen) then return
    if n_elements(xcrs) eq 0 then xcrs=.9*!d.x_vsize 
    if n_elements(ycrs) eq 0 then ycrs=.9*!d.y_vsize 
    tvcrs,xcrs,ycrs
  endif
  device,cursor_standard=16
  cursor,xdum,ydum,/wait,/device
  if keyword_set(up) then cursor,xdum,ydum,/up,/device
  device,cursor_standard=30
endif
end