;+
; This procedure places a text string on the plot
;
; @param x {in}{required}{type=float} X position of the string
; @param y {in}{required}{type=float} Y position of the string
; @param text {in}{required}{type=string} The text to write
; @keyword color {in}{optional}{type=integer}{default=!g.annotatecolor}
; Text color index
; @keyword charsize {in}{optional}{type=float} character size
; @keyword normal {in}{optional}{type=boolean} positions are
; normalized coordinates.
; @keyword noshow {in}{optional}{type=boolean} Don't immediately show
; the new annotation.  This is useful if you are stringing several
; annotations together.  It keeps the plotter from updating after each
; call.
;
; @examples
;    annotate,10.5,1.5,'Hello',color=!blue,charsize=2.0
;
; @version $Id: annotate.pro,v 1.6 2005/04/29 06:02:19 bgarwood Exp $
;-

pro annotate,x,y,text,color=color,charsize=charsize,normal=normal,noshow=noshow
    common gbtplot_common,mystate,xarray
    if n_params() ne 3 then begin
       message,'Usage: annotate, x, y, text[,color=color,charsize=charsize,/normal,/noshow]',/info
       return
    endif
    if mystate.n_annotations eq 99 then begin
        print,'Max number of annotations is 100'
        return
    end
    mystate.n_annotations = mystate.n_annotations+1
    mystate.annotation[mystate.n_annotations-1] = text
    mystate.xyannotation[mystate.n_annotations-1,*] = [x,y]
    if n_elements(color) ne 0 then mystate.ann_color[mystate.n_annotations-1] = color $
        else mystate.ann_color[mystate.n_annotations-1] = !g.annotatecolor
    if n_elements(charsize) ne 0 then mystate.ann_charsize[mystate.n_annotations-1] = charsize $
        else mystate.ann_charsize[mystate.n_annotations-1] = 1.0
    mystate.ann_normal[mystate.n_annotations-1] = keyword_set(normal)
    if (not keyword_set(noshow)) then show,/reshow
end