;+
; NAME:
;	plot_legend.pro
;
; PURPOSE:
;	draw a legend on an existing plot
;	the legend is drawn with
;	a) a line
;	b) a line with a symbol at each line end
;	c) a single symbol
;	the legend text can be plotted at any position to the left
;		or right of the legend line/symbol
;	the position of the legend and text has to be given in normal coos (0-1)
;	
; CATEGORY:
;	plot utitlities
;
; CALLING SEQUENCE:
;	plot_legend,legend,text=text,charsize=charsize,color=color,$
;		linethick=linethick,symsize=symsize
;
; EXAMPLE:
;
; INPUTS:
;	legend		FltArr(n,6): n is the number of the legend elements
;			For each legend element 6 parameters must be
;			provided:
;			legend(*,0): The y position of each element
;			legend(*,1): The x position of the left line end
;			legend(*,2): The x position of the right line end
;			legend(*,3): The x (start) position of the text
;			legend(*,4): The linestyle number (-1 for no line)
;			legend(*,5): The symbol number (-1 or 0 for no symbol)
;
; OPTIONAL INPUT PARAMETERS:
;	text		StrArr(n): the text for each legend element
;	charsize	the legend text size
;	color		IntArr(n): the color of each legend line/symbol
;	linethick	IntArr(n): the thickness of each legend line
;	symthick	IntArr(n): the symbol thicknesses
;	symsize		IntArr(n): the symbol sizes for each legend element
;       charthick	Float: the character thickness for the text (default=1)
;
; KEYWORD INPUT PARAMETERS:
;
; OUTPUTS:			
;
; COMMON BLOCKS:
;
; SIDE EFFECTS:
;
; RESTRICTIONS:
;	
; PROCEDURE:
;	
; MODIFICATION HISTORY:
;	first implementation July 30, 1997 by Dominik Brunner
;-
pro plot_legend,legend,text=text,charsize=charsize,color=color,$
	linethick=linethick,symsize=symsize,charthick=charthick,$
	symthick=symthick

;------------- check for input parameters ---------------------
IF n_elements(legend) EQ 0 THEN BEGIN
   print,'parameter leg missing in call to legend'
   return
ENDIF

IF n_elements(charthick) NE 1 THEN charthick=1	; default character thickness
leg=transpose(legend)

nleg=n_elements(leg(0,*))

IF n_elements(text) GT 0 THEN BEGIN
   IF n_elements(text) NE nleg THEN BEGIN
      print,'Error! number of text elements must be ',nleg
      return
   ENDIF
ENDIF ELSE text=StrArr(nleg)

IF n_elements(color) GT 0 THEN BEGIN
   IF n_elements(color) NE nleg THEN BEGIN
      print,'Error! number of color elements must be ',nleg
      return
   ENDIF
ENDIF ELSE color=IntArr(nleg)+!P.Color

IF n_elements(linethick) GT 0 THEN BEGIN
   IF n_elements(linethick) NE nleg THEN BEGIN
      print,'Error! number of linethick elements must be ',nleg
      return
   ENDIF
ENDIF ELSE linethick=IntArr(nleg)+1

IF n_elements(symthick) GT 0 THEN BEGIN
   IF n_elements(symthick) NE nleg THEN BEGIN
      print,'Error! number of symthick elements must be ',nleg
      return
   ENDIF
ENDIF ELSE symthick=IntArr(nleg)+1

IF n_elements(symsize) GT 0 THEN BEGIN
   IF n_elements(symsize) NE nleg THEN BEGIN
      print,'Error! number of symsize elements must be ',nleg
      return
   ENDIF
ENDIF ELSE symsize=IntArr(nleg)+1


;--------------- loop over each leg element -------------
FOR i=0,nleg-1 DO BEGIN

    ; draw the line and symbols
    IF leg(4,i) GT -1 THEN BEGIN
       plots,[leg(1,i),leg(2,i)],[leg(0,i),leg(0,i)],$
	     color=color(i),linestyle=leg(4,i),thick=linethick(i),/norm
       IF leg(5,i) GT 0 THEN $
          plots,[leg(1,i),leg(2,i)],[leg(0,i),leg(0,i)],$
	         psym=leg(5,i),color=color(i),symsize=symsize(i),thick=symthick[i],/norm
    ENDIF ELSE BEGIN
       IF leg(5,i) GT 0 THEN $
	  plots,leg(1,i),leg(0,i),psym=leg(5,i),$
		color=color(i),symsize=symsize(i),thick=symthick[i],/norm
    ENDELSE

    ; plot the text
    XYOUTS,leg(3,i),leg(0,i),text(i),charsize=charsize,/norm,charthick=charthick

ENDFOR

END