;+
; NAME:
;       PLOTCBAR
;
; PURPOSE:
;       Add a vertical colour bar to a plot.
;
; CATEGORY:
;       Plotting tools.
;
; CALLING SEQUENCE:
;       plotcbar, values, colour, barpos [, ctable][, barlab=barlab] 
;                 [, tickle=tickle] [, majval=majval] [, minval=minval] 
;                 [, format=format] [, /endlab]
;
; REQUIRED INPUTS:
;       values      data values or minimum and maximum of data range
;       colour      colour values corresponding to the data values
;       barpos      position of the colour bar in device coordinates
;
; OPTIONAL INPUTS:
;       ctable      number of the color table to be used
;
; KEYWORDS:
;       barlab      title for the right axis of the colour table
;       tickle      length of the major tick marks
;       majval      data values of the major tick marks
;       minval      data values of the minor tick marks
;       format      format string for the tick marks
;       endlab      lable the endpoints of the colour range
;
; OUTPUTS:
;       none
;
; DESCRIPTION AND EXAMPLE:
;       The procedure plots a vertical colour bar at a specified position. 
;       This is a low level routine mainly intended for being called by 
;       other routines.
;
; CALLED BY:
;       plotfits
;       midi_pltuvp
;
; CALLING:
;       none.
;
; MODIFICATION HISTORY:
;       2009-02-20 Written by Konrad R. Tristram
;       2010-08-11 K. Tristram: Removed usage of spline in interpol.
;

PRO PLOTCBAR, VALUES, COLOUR, BARPOS, CTABLE, BARLAB=BARLAB, TICKLE=TICKLE, $
              MAJVAL=MAJVAL, MINVAL=MINVAL, FORMAT=FORMAT, ENDLAB=ENDLAB

; SET HOW MANY STEPS THERE WILL BE ALONG THE COLOUR DIRECTION
;-------------------------------------------------------------------------------
numele = 2551

; CHECK AND INITIALISE DEFAULT VALUES FOR SOME VARIABLES
;-------------------------------------------------------------------------------
valpos = findgen(n_elements(values))/(n_elements(values)-1)
nolabl = replicate(' ', 60)
if n_elements(ctable)  eq 0 then ctable = 39b $
                            else ctable = (byte(ctable[0])) < 45b
if n_elements(barlab)  eq 0 then barlab = ' ' else barlab = string(barlab)
if n_elements(tickle)  eq 0 then tickle = 0.29
if size(format, /type) ne 7 then format = ''

; EXPAND THE COLOUR ARRAY TO A 2551 ELEMENT ARRAY IF NECESSARY
;-------------------------------------------------------------------------------
if n_elements(colour) ne numele then begin
	tmpvar = n_elements(colour)
	colarr = interpol(colour, findgen(tmpvar)/(tmpvar-1), $
	                          findgen(numele)/(numele-1))
endif else colarr = colour

; PLOT THE COLORS USING THE COLOR ARRAY
;-------------------------------------------------------------------------------
plot, [0,1], [0,255], xs=5, ys=5, position=barpos, /nodata, /noerase, /device
loadct, ctable, /silent
for i=0,numele-1 do oplot, [0,1], [i/10.,i/10.], color=colarr[i]
loadct, 39, /silent

; CREATE THE X-AXIS AND DEFINE A [0, 1] COORDINATE SYSTEM
;-------------------------------------------------------------------------------
plot, [0,1], [0,1], xs=1, ys=5, xticks=1, xtickname=[' ', ' '], $
      position=barpos, /nodata, /noerase, /device

; PLOT THE MINOR TICK MARKS IF VALUES PROVIDED
;-------------------------------------------------------------------------------
if n_elements(minval) gt 0 then begin
	tmpidx = where((minval gt min(values)) and (minval lt max(values)))
	minpos = interpol(valpos, values, minval[tmpidx], /spline)
	if keyword_set(endlab) then minpos = [0., minpos, 1.]
	axis, yaxis=0, yrange=[0,1], ystyle=1, yticklen=0.5*tickle, $
	      ytickv=minpos, yticks=n_elements(minpos)-1, ytickname=nolabl
	axis, yaxis=1, yrange=[0,1], ystyle=1, yticklen=0.5*tickle, $
	      ytickv=minpos, yticks=n_elements(minpos)-1, ytickname=nolabl
endif

; PLOT THE MAJOR TICK MARKS IF VALUES PROVIDED
;-------------------------------------------------------------------------------
if n_elements(majval) gt 0 then begin
	tmpidx = where((majval gt min(values)) and (majval lt max(values)))
	majpos = interpol(valpos, values, majval[tmpidx])
	if keyword_set(endlab) then begin
		majpos = [0., majpos, 1.]
		majnam = [min(values), majval[tmpidx], max(values)]
	endif else majnam = majval[tmpidx]
	majnam = string(majnam, format=format)
	axis, yaxis=0, yrange=[0,1], ystyle=1, yticklen=tickle, $
	      ytickv=majpos, yticks=n_elements(majpos)-1, ytickname=nolabl
	axis, yaxis=1, yrange=[0,1], ystyle=1, yticklen=tickle, $
	      ytickv=majpos, yticks=n_elements(majpos)-1, ytickname=majnam, $
	      ytitle=barlab
endif

; OTHERWISE PLOT LINEAR SCALING FROM MINIMUM TO MAXIMUM
;-------------------------------------------------------------------------------
if (n_elements(majval) le 0) and (n_elements(majval) le 0) then begin
	axis, yaxis=0, yrange=[values[0], values[n_elements(values)-1]], $
	      ystyle=1, yticklen=tickle, ytickname=nolabl
	axis, yaxis=1, yrange=[values[0], values[n_elements(values)-1]], $
	       ystyle=1, yticklen=tickle, ytitle=barlab
endif

END