;+
; NAME:
;	TIMEAXISD
;
; PURPOSE:
;	This procedure can be used to plot a time axis at the bottom of
;	the current draw window. Additional tickmarks can be displayed
;	by passing the name of a conversion routine to the procedure,
;	which maps the time tickmark values to the additional tickmarks.
;	The conversion routine should accept the following four arguments:
;
;	Input:	- the actual time tickmark values
;
;	Output:	- the additional tickmark values
;		- the axis label(s)
;		- the parameter unit(s)
;
; CATEGORY:
;	Plot routines.
;
; CALLING SEQUENCE:
;       TIMEAXISD, range [, routine]
;
; INPUTS:
;	range	The actual time range. This range is extended if the keyword
;		EXACT is not set.
;
;	routine	An optional string containg the name of the tickmark
;		conversion routine.
;
; KEYWORD PARAMETERS:
;       EXACT	Set this keyword to use the exact time range, otherwise the
;		time range is extended.
;
;	LABEL	Set this keyword to a string containing the time axis label.
;		The default is 'Time'.
;
;	UNIT	Set this keyword to a string containing the time axis unit.
;		The default is 'UT'.
;
;	SAVE	Set this keyword to save the time axis annotaion value in
;		the !X system variable.
;
;	COLOR	Set this keyword to the color index used for the axis.
;
;	FONT	A string containing the vector font index to use. The default
;		is '!3'.
;
;	SIZE	The character size to use.
;
; OUTPUTS:
;	range	The resulting time range.
;
; COMMON BLOCKS:
;	None.
;
; SIDE EFFECTS:
;	The procedure evaluates the !P.MULTI system variable to get the
;	position of the last plot window. If the SAVE keyword is set,
;	the time annotation values are stored in the !X system variable.
;
;	Caution: The !X.TICKV values are relative to the minimum range
;		 value !!!
;
; PROCEDURE:
;
;	;
;	; Define two axis labeling procedure(s).
;	;
;	PRO RelativeMin, timeTicks, hourRange, label, unit, isRange
;	    hourRange = (timeTicks([0,N_ELEMENTS(timeTicks)-1]) - $
;			 timeTicks(0))/60000.0D
;	    label = 'Relative Time'
;	    unit = 'minutes'
;	    isRange = 1B
;	END ; RealiveMin
;
;	PRO InverseCount, timeTicks, countTicks, label, unit, isRange
;	    nTicks  = N_ELEMENTS(timeTicks)
;	    countTicks = nTicks - INDGEN(nTicks) - 1
;	    label = 'Inverse count'
;	    unit  = ''
;	    isRange = 0B
;	END
;
;	;
;	; Create and display sample data.
;	;
;	!X.MARGIN = [10,6]
;	!Y.MARGIN = [ 8,4]
;
;	CDF_EPOCH, epoch, 1996, 1, 1, /COMPUTE
;	time  = epoch + dindgen(11)*3600000.0D
;	data  = SIN(INDGEN(11)*!PI*0.2)
;	range = [time(0), time(10)]
;
;	ERASE
;	TIMEAXISD, range, ['RelativeMin','InverseCount']
;	PLOT, time-range(0), data, XSTYLE=5, /NOERASE, XRANGE=range-range(0)
;
; MODIFICATION HISTORY:
;	Written by:	DI Harald Jan Jeszenszky, 03/97.
;	1998-12-29 HJJ	Added top axis. Modified example program.
;-
PRO TIMEAXISD, range, routine, LABEL=label, UNIT=unit, EXACT=exact, $
			      SAVE=save, COLOR=color, FONT=font, $
			      SIZE=size

    IF (N_ELEMENTS(label) EQ 0) THEN label = 'UT'
    IF (N_ELEMENTS(unit) EQ 0)  THEN unit  = ''
    IF (N_ELEMENTS(color) EQ 0) THEN color = !P.COLOR
    IF (N_ELEMENTS(font) EQ 0) THEN font = '!3'
    IF (N_ELEMENTS(size) EQ 0) THEN size = 1.0

    ;
    ; save system variables
    ;
    xSave = !X
    ySave = !Y
    pSave = !P

    xChar = FLOAT(!D.X_CH_SIZE) / !D.X_VSIZE * size
    yChar = FLOAT(!D.Y_CH_SIZE) / !D.Y_VSIZE * size

    ;
    ; plot sample data to get coordinates of the labeling window
    ;
    nPanels = (!P.MULTI(1) > 1)*(!P.MULTI(2) > 1)
    !P.MULTI(0) = 1
    PLOT, [0], /NODATA, /NOERASE, XSTYLE=4, YSTYLE=4

    ;
    ; plot time axis
    ;
    ticks = EP_TICKSD(range, tickv, tickname, minor, EXACT=KEYWORD_SET(exact))
    IF KEYWORD_SET(save) THEN BEGIN
	xSave.TICKS = ticks
	xSave.MINOR = minor
	xSave.TICKV = tickv - range(0)
	xSave.TICKNAME = tickname
	xSave.CRANGE = range
    ENDIF

    AXIS, !X.WINDOW(0), !Y.WINDOW(0), /NORMAL, XAXIS=0, XSTYLE=1, $
	  XRANGE=range-range(0), COLOR=color, $
	  XTICKS=ticks, XMINOR=minor, XTICKV=tickv-range(0), $
	  XTICKNAME=font+tickname, XTICKFORMAT='(A1)'

    ; plot 2nd axis, 1998-12-29, HJJ

    AXIS, !X.WINDOW(0), !Y.WINDOW(1), /NORMAL, XAXIS=1, XSTYLE=1, $
	  XRANGE=range-range(0), COLOR=color, $
	  XTICKS=ticks, XMINOR=minor, XTICKV=tickv-range(0), $
	  XTICKNAME=font+tickname, XTICKFORMAT='(A1)'

    ;
    ; calculate normalised tickmark positions
    ;
    xPos = !X.WINDOW(0) + (tickv - range(0))/(range(1) - range(0)) * $
    			  (!X.WINDOW(1) - !X.WINDOW(0))
    yPos = !Y.WINDOW(0) + FLTARR(N_ELEMENTS(tickv))

    ;
    ; plot time tickmarks
    ;

    XYOUTS, xChar, yPos(0)-yChar, /NORMAL, COLOR=color, $
    	    font + label, CHARSIZE=size
    XYOUTS, 1-xChar, yPos(0)-yChar, /NORMAL, ALIGN=1.0, COLOR=color, $
    	    font + unit, CHARSIZE=size
    XYOUTS, xPos, yPos-yChar, /NORMAL, ALIGN=0.5, COLOR=color, $
    	    font + tickname, CHARSIZE=size

    ;
    ; Plot additional tickmarks.
    ;
    IF (N_ELEMENTS(routine) EQ 1) THEN BEGIN
    	CALL_PROCEDURE, routine, tickv, tickname, label, unit
	nLines = N_ELEMENTS(label)
	nMarks = N_ELEMENTS(tickv)
	tickname = REFORM(tickname, nLines, nMarks)
	yPos = yPos - 3*yChar

	FOR i = 0, nLines-1 DO BEGIN
	    yPos = yPos - yChar
	    XYOUTS, xChar, yPos(0), /NORMAL, COLOR=color, $
	    	    font + label(i), CHARSIZE=size
	    XYOUTS, 1-xChar, yPos(0), /NORMAL, ALIGN=1.0, COLOR=color, $
	    	    font + unit(i), CHARSIZE=size
	    XYOUTS, xPos, yPos, /NORMAL, ALIGN=0.5, COLOR=color, $
	    	    font + STRING(tickname(i,*)), CHARSIZE=size
	ENDFOR
    ENDIF

    ;
    ; restore system variables
    ;
    !P = pSave
    !Y = ySave
    !X = xSave

END ; TIMEAXISD