;---------------------------------------------------------------------------
; Document name: PLOT_FRAME.PRO
; Created by:    William Thompson, GSFC, 15 July 1993
;
; Last Modified: Tue Jan 16 17:23:44 1996 (lwang@achilles.nascom.nasa.gov)
;---------------------------------------------------------------------------
;
;+
; Project     :	SOHO - CDS
;
; Name        :	PLOT_FRAME
;
; Purpose     :	Plots frame for science planning tool.
;
; Explanation :	This routine is used by the science planning tool to plot the
;		frame within which the plan will be drawn.
;
; Use         :	PLOT_FRAME, T1, T2
;
; Inputs      :	T1, T2	= The beginning and end time of the plot, in hours.
;
; Opt. Inputs :	None.
;
; Outputs     :	None.
;
; Opt. Outputs:	None.
;
; Keywords    :	CHARSIZE = The character size for the text labels.  If not
;			   passed, then determined from !P.CHARSIZE.
;
;		XTITLE	 = An optional ASCII string to be the X-axis title.
;
;		LOCAL	 = If set, then also show the local time across the top
;			   of the figure.  It is assumed that T1 and T2 are in
;			   UTC.
;
;               YLABELS  = ylabels to go with each row
;
;
; Calls       :	LOCAL_DIFF
;
; Common      :	None.
;
; Restrictions:	None.
;
; Side effects:	None.
;
; Category    :	Planning, Science.
;
; Prev. Hist. :	None.
;
; Written     :	William Thompson, GSFC, 15 July 1993.
;
; Modified    :	Version 1, William Thompson, GSFC, 15 July 1993.
;		Version 2, William Thompson, GSFC, 28 March 1994.
;			Changed label to "CDS-details".
;		Version 3, Elaine Einfalt, GSFC (HSTX), Apr 94.
;			Added optional XTITLE keyword.
;		Version 4, William Thompson, GSFC, 2 November 1994
;			Added LOCAL keyword
;               Version 5, Zarro, GSFC, 20 February 1994
;                       Added YLABELS
;               Version 6, Liyun Wang, GSFC/ARC, June 22, 1995
;                       Made ticklength appear the same for both axes 
;                          regardless of aspect ratio of the window
;               Version 7, Liyun Wang, GSFC/ARC, January 16, 1996
;                       Fixed problem of X, Y labels appearing
;                          different when plot in PS format
; Version     :	Version 7
;-

PRO plot_frame, t1, t2,charsize=charsize,xtitle=xtitle,local=local,$
                ylabels=ylabels,_extra=extra,color=color

   ON_ERROR, 1
;
;  check the number of parameters.
;
   IF N_PARAMS() NE 2 THEN MESSAGE, 'Syntax: plot_frame, t1, t2'
   IF NOT KEYWORD_SET(local) THEN local = 0
   IF N_ELEMENTS(xtitle) EQ 0 THEN xtitle = ''
   IF N_ELEMENTS(ylabels) EQ 0 THEN ylabels = ''
   nrows = N_ELEMENTS(ylabels)
   
;
;  make ticklength in both axes appear the same
   
   ticklen_sv = !p.ticklen
   xticklen_sv = !x.ticklen
   yticklen_sv = !y.ticklen

   !p.ticklen = 0.02
   !x.ticklen = !p.ticklen
   !y.ticklen = !p.ticklen
   
   IF (!d.x_size GT !d.y_size) THEN BEGIN
      !x.ticklen = (!d.x_size/!d.y_size)*!y.ticklen
   ENDIF ELSE BEGIN
      !y.ticklen = (!d.y_size/!d.x_size)*!x.ticklen
   ENDELSE
;
;  get the character size.
;
   IF N_ELEMENTS(charsize) EQ 0 THEN BEGIN
      IF !p.charsize GT 0 THEN charsize = !p.charsize ELSE	$
         charsize = 1
   ENDIF
;
;  make the plot frame, but don't plot the x axis.  if the local keyword was
;  set, then leave enough room for the supertitle.
;
   ymargin = !y.margin
   IF KEYWORD_SET(local) THEN ymargin(1) = MAX(ymargin)
   plot, [t1, t2], [0, nrows], /nodata, xstyle=5, ystyle=1, yticks=nrows, $
      ytickname=REPLICATE(' ', nrows+1), xmargin=[15, 4], $
      xtick_get=xticks, psym=0, linestyle=0, ymargin=ymargin, _extra=extra
;
;  plot the x axis with time format labels.
;
   hours = FIX(xticks) MOD 24
   w = WHERE(hours LT 0, count)
   IF count GT 0 THEN hours(w) = hours(w) + 24
   minutes = 60*(xticks - FIX(xticks))
   w = WHERE(minutes LT 0, count)
   IF count GT 0 THEN BEGIN
      hours(w) = hours(w) - 1
      minutes(w) = minutes(w) + 60
   ENDIF
   w = WHERE(minutes GE 60, count)
   IF count GT 0 THEN BEGIN
      hours(w) = hours(w) + 1
      minutes(w) = minutes(w) - 60
   ENDIF
   hours = STRMID(STRING(100+hours, FORMAT='(i3)'), 1, 2)
   minutes = STRMID(STRING(100+FIX(minutes+0.5), FORMAT='(i3)'), 1, 2)

   if exist(color) then $
    axis, xaxis=0, xstyle=1, xtickname=hours+':'+minutes, xtitle=xtitle, $
     charsize=charsize,color=color else $
      axis, xaxis=0, xstyle=1, xtickname=hours+':'+minutes, xtitle=xtitle, $
       charsize=charsize
  
;
;  if requested, also put the local time across the top.  otherwise, simply
;  replicate the tick marks from below.
;
   IF KEYWORD_SET(local) THEN BEGIN
      hours = FIX(hours) + round(local_diff())
      w = WHERE(hours LT 0, count)
      IF count GT 0 THEN hours(w) = hours(w) + 24
      hours = STRMID(STRING(100+hours, FORMAT='(i3)'), 1, 2)
      if exist(color) then $
       axis, xaxis=1, xstyle=1, xtickname=hours+':'+minutes, $
        xtitle='(Local Time)', charsize=charsize,color=color else $
         axis, xaxis=1, xstyle=1, xtickname=hours+':'+minutes, $
          xtitle='(Local Time)', charsize=charsize
   END ELSE begin
    if exist(color) then $
     axis, xaxis=1, xstyle=1, xtickname=REPLICATE(' ', 30), $
      charsize=charsize,color=color else $
       axis, xaxis=1, xstyle=1, xtickname=REPLICATE(' ', 30), $
        charsize=charsize
   endelse

;  draw the lines between rows.
;
   dy = !d.y_ch_size * charsize / (3 * !y.s(1) * !d.y_size)
   FOR i=1, nrows DO BEGIN

    if exist(color) then $
     OPLOT, [t1, t2], [i, i], psym=0, linestyle=0,color=color else $
      OPLOT, [t1, t2], [i, i], psym=0, linestyle=0
      xc = t1 & yc=i-1+.5-dy
    
    if exist(color) then $
     xyouts, xc, yc, align=1, ylabels(i-1)+blank(1),charsize=charsize,color=color else $
      xyouts, xc, yc, align=1, ylabels(i-1)+blank(1),charsize=charsize
     
   ENDFOR

;
;  restore !p
;
   !p.ticklen = ticklen_sv
   !x.ticklen = xticklen_sv
   !y.ticklen = yticklen_sv
   
   RETURN
END

;---------------------------------------------------------------------------
; end of 'plot_frame.pro'.
;---------------------------------------------------------------------------