;+-------------------------------------------------------------
; NAME:
;       mplottitle
; PURPOSE:
;       write a plot title with NSTX label and a list of shots on left
; CATEGORY:
;       Plotting
; CALLING SEQUENCE:
;       IDL> mplottitle, screenTitle, shots, HLP=hlp, $
;	     COLORS=colors, LOGO=logo, $
;	     CHARMAG=charMag, TopMargin=TopMargin, RIGHT=right, $
;	     INSIDE=inside, XPOS=xPos
; INPUTS:
;       screenTitle = whatever you want as the main plot title.  
;       shots = array of shot numbers.
;	
; KEYWORD PARAMETERS:
;	HLP - When set, help information is printed.
;	colors - color indices of each shot number (default = !p.color)
;	logo - Characters to draw above shot list. Default = '=NSTX=
;	TopMargin - in characters, extra space to shift down the characters
;	right - if set, labels put on left
;	inside - if set, lists shots inside plot box
;	xPos - xPos, in Device Coordinates, for left side of shot list
;		(overrides /RIGHT & /INSIDE)
; OUTPUTS:
;       none
; COMMON BLOCKS:
;       NONE
; EXAMPLES:
;	IDL> !Y.OMARGIN=[0,1]
;	IDL> plot,indgen(100)
;	IDL> mplottitle, 'This is my title', [100523,100544]
;	IDL> plot,indgen(100)
;	IDL> cs=mk_color(/load, /quiet)
;	IDL> colors=[cs.black, cs.red, cs.green, cs.blue, cs.magenta]
;	IDL> mplottitle,' ', shots, colors=colors, logo='Shots:', $
;                           charMag=1.35, topMargin=0.5
; NOTES:
;       You'll probably want a little more room at the top of your plots, e.g.
;	IDL> !Y.OMARGIN=[0,1]
; MODIFICATION HISTORY:
;	19-Jan-06 Added psym keyword
;	01-Oct-01 Added keywords for inside & right [BD]
;       21-Sep-99 Written by Bill Davis, PPPL
;--------------------------------------------------------------
PRO mplottitle, screenTitle, shots, HLP=hlp, COLORS=colors, LOGO=logo, $
                CHARMAG=charMag, TOPMARGIN=TopMargin, LEFT=left, RIGHT=right, $
		psym=psym, $
		INSIDE=inside, XPOS=xPos, OUTSIDE=outside

IF (N_PARAMS(0) EQ 0) or KEYWORD_SET(hlp) THEN BEGIN
     PRINT,' write a plot title with shot date and time and NSTX label'
     PRINT,' IDL> mplottitle, mytitle, shots'
     RETURN
ENDIF

if n_elements( charMag ) eq 0 then charMag=1
if n_elements( logo ) eq 0 then logo='=NSTX='

if n_elements( TopMargin ) eq 0 then TopMargin=0

topScreen = 780 < !D.Y_Size	; lesser value since !D.Y_Size doesn't work
IF  !d.name NE 'SGLIB' THEN topScreen = !D.Y_Size*0.980 


IF NWORDS( screenTitle ) GT 0 THEN $
   xyouts, !d.X_Size/2, topScreen-((0.8+TopMargin)*!D.Y_CH_Size*charMag), $	; 
           screenTitle, charsize=1.5*charMag, ALIGNMENT=0.5, /DEVICE

aLittleMore = 0
IF !Y.OMargin[1] GT 0 THEN aLittleMore = !Y.OMargin[1]/!D.Y_CH_Size
line1 = 0.3 + aLittleMore + TopMargin
line2 = line1 + 1.1
delta = ABS( line2 - line1 )

nshots = N_ELEMENTS(shots)
if n_elements(colors) EQ 0 then colors=replicate(!p.color,(nshots>1))
ncolors= N_ELEMENTS(colors)

if n_elements( shots ) gt 0 then begin
   nChars = strlen( strtrim( shots,2 ) )
   StrLen = MAX( nChars )

   if NWORDS( xPos ) EQ 0 then begin
      if not keyword_set( right ) then begin	; on the left
	 if keyword_set( inside ) then begin
	    xPos = !D.X_CH_Size * ( 1 + !X.OMargin[0] + !X.Margin[0] )
	 endif else begin
	    xPos = !D.X_CH_Size * 0.66	; start in 2/3 character width
	 endelse
      endif else begin				; on the right
	 if keyword_set( inside ) then begin
	    xPos = !D.X_Size - !D.X_CH_Size*charMag * $
	                	  (StrLen+1 + !X.OMargin[1]+!X.Margin[1] )
	 endif else begin
	    xPos = !D.X_Size - (StrLen+0.66)*!D.X_CH_Size*charMag	; 6 & 2/3 chars from right
	 endelse
      endelse
   endif

   if keyword_set( inside ) then yPosStart = !y.window[1]*!d.y_size  $
                            else yPosStart = topScreen

   for i = 0, nshots-1 do begin
      ishot = shots[i]
      strshot = STRTRIM(ishot,2)

      ; on the left
      xyouts, xPos, yPosStart-((i+1)*delta* $
              !D.Y_CH_Size*charMag) - (line1*!D.Y_CH_Size*charMag), $
	      strshot, color=colors( i MOD ncolors), $
              charsize=0.9*charMag, ALIGNMENT=0.0, /DEVICE
      if n_elements( psym ) ge i+1 then begin
	 plots, xPos+(!D.X_CH_Size*charMag)*(STRLEN(strshot)+0.5),   $
        	yPosStart-((i+0.75)*delta*!D.Y_CH_Size*charMag) - $
		(line1*!D.Y_CH_Size*charMag), $
		 color=colors( i MOD ncolors), $
        	psym=psym[i], /DEVICE, symsize=1.5
      endif
   endfor
   
endif
if logo ne '0' then begin
   IF !P.FONT EQ -1 THEN BEGIN	; using Hershey fonts
      xyouts, !D.X_CH_Size, topScreen-(line1*!D.Y_CH_Size*charMag), $
              '!6'+STRING(logo), $
              charsize=0.9*charMag, ALIGNMENT=0.0, /DEVICE
   ENDIF ELSE BEGIN
      xyouts, !D.X_CH_Size, topScreen-(line1*!D.Y_CH_Size), logo, $
              charsize=0.9*charMag, ALIGNMENT=0.0, /DEVICE
   ENDELSE

   XYOUTS, .2, .5, '!3', /normal	; set back to default font type
endif

RETURN
END