;---------------------------------------------------------------------------
; Document name: PLOT_UTFRAME.PRO
; Created by:    Liyun Wang, GSFC/ARC, May 8, 1996
;
; Last Modified: Mon May 13 09:39:30 1996 (lwang@achilles.nascom.nasa.gov)
;---------------------------------------------------------------------------
;
;+
; PROJECT:
;       SOHO - CDS/SUMER
;
; NAME:
;       PLOT_UTFRAME
;
; PURPOSE: 
;       Plots frame for science planning tool
;
; CATEGORY:
;       Planning, Science
; 
; EXPLANATION:
;       This routine is used by the science planning tool to plot the
;	frame within which the plan will be drawn. Time marks are
;	properly made.
;       
; SYNTAX: 
;       plot_utframe, t1, t2, basetime
;
; INPUTS:
;       T1, T2	 - The beginning and end time of the plot, in hours
;       BASETIME - Base time, in any CDS time format
;
; OPTIONAL INPUTS: 
;       None.
;
; OUTPUTS:
;       None.
;
; OPTIONAL 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
;
; COMMON:
;       None.
;
; RESTRICTIONS: 
;       None.
;
; SIDE EFFECTS:
;       None.
;
; HISTORY:
;       Version 1, May 8, 1996, Liyun Wang, GSFC/ARC. Written
;          Modified from PLOT_FRAME by William Thompson, GSFC
;       Version 2, May 10, 1996, Liyun Wang, GSFC/ARC
;          Plotted local time separately in the same way as UT
;
; CONTACT:
;       Liyun Wang, GSFC/ARC (Liyun.Wang.1@gsfc.nasa.gov)
;-
;
PRO plot_utframe, t1, t2, basetime, charsize=charsize, xtitle=xtitle, $
                  local=local, ylabels=ylabels, _extra=extra, color=color

   ON_ERROR, 1
;---------------------------------------------------------------------------
;  check the number of parameters.
;---------------------------------------------------------------------------
   IF N_PARAMS() NE 3 THEN MESSAGE, 'Syntax: plot_utframe, 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)

   mk_timetick, t1, t2, basetime, label=tickname, value=value, $
      major=major, minor=minor
   
   x_save = !x.range
   !x.range = [t1, t2]

   
   stat="PLOT, [t1, t2], [0, nrows], /nodata, xstyle=5, ystyle=1,"+$
        " yticks=nrows, ytickname=REPLICATE(' ', nrows+1), xmargin=[15, 5],"+$
        " xtickv=value, xtickname=tickname, xticks=major, xminor=minor,"+$
        " xtitle=xtitle, psym=0, linestyle=0, ymargin=ymargin,"+$
        " charsize=charsize "
   if exist(color) then stat=stat+',color=color'
   s=execute(stat)

;---------------------------------------------------------------------------
;  Plot lower X-axis
;---------------------------------------------------------------------------
   IF exist(color) THEN BEGIN 
      AXIS, xaxis=0, xstyle=1, xtickname=tickname, xticks=major, $
         xminor=minor, xtitle=xtitle, charsize=charsize, $
         xtickv=value, color=color 
   ENDIF ELSE BEGIN
      AXIS, xaxis=0, xstyle=1, xtickname=tickname, xticks=major, $
         xminor=minor, xtitle=xtitle, charsize=charsize, $
         xtickv=value
   ENDELSE
   
;---------------------------------------------------------------------------
;  Plot upper X-axis
;---------------------------------------------------------------------------
   IF KEYWORD_SET(local) THEN BEGIN
      gap = ROUND(local_diff())
      !x.range = !x.range+gap
      IF !x.range(0) LT 0.0 THEN !x.range = !x.range+24.0
      
      mk_timetick, t1, t2, basetime, label=tickname, value=value,  $
         major=major, minor=minor, /local
      
      IF exist(color) THEN BEGIN 
         AXIS, xaxis=1, xstyle=1, xtickname=tickname, xticks=major, $
            xminor=minor, xtitle='(Local Time)', charsize=charsize, $
            xtickv=value, color=color 
      ENDIF ELSE BEGIN 
         AXIS, xaxis=1, xstyle=1, xtickname=tickname, xticks=major, $
            xminor=minor, xtitle='(Local Time)', charsize=charsize, $
            xtickv=value
      ENDELSE
   ENDIF ELSE BEGIN
      IF exist(color) THEN BEGIN
         AXIS, xaxis=1, xstyle=1, xtickname=REPLICATE(' ', 30), $
            charsize=charsize, xticks=major, xminor=minor, xtickv=value, $
            color=color 
      ENDIF ELSE BEGIN 
         AXIS, xaxis=1, xstyle=1, xtickname=REPLICATE(' ', 30), $
            xtickv=value, xticks=major, xminor=minor, charsize=charsize
      ENDELSE
   ENDELSE
   
   !x.range = x_save
;---------------------------------------------------------------------------
;  draw the lines between rows
;---------------------------------------------------------------------------
   dy = !d.y_ch_size * charsize / (3 * !y.s(1) * !d.y_size)
   FOR i=0, 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 i gt 0 then begin
       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
      endif
   ENDFOR

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

   RETURN
END

;---------------------------------------------------------------------------
; end of 'plot_utframe.pro'.
;---------------------------------------------------------------------------