;+
; NAME:
;       DRAW_LIMITS
; PURPOSE:
;       Draw left-, under-, right-, upper-limits to a point in the
;       form of an arrow
; CALLING SEQUENCE:
;       draw_limits, X, Y, direction=direction[,length=length][,/help]
; EXAMPLES:
;       draw_limits,/help displays this information
;       draw_limits,[1.0, 1.0], [1.0, 1.0], direction=[1,2], length=[0.01,0.1]
;           draws an arrow in the direction of both the +x and +y
;           direction on the data-point (1.0, 1.0). The length of the
;           arrow will be 0.01 in the normalized space in the +x
;           direction and 0.1 in the normalized space in the +y
;           direction.
;           As length works in the normalized space you might be
;           warned that it never can be bigger than 1.0 (it will cross
;           the boundaries of the plot) or in conjunction with
;           MULTIPLOT it can't be bigger than a value smaller
;           than 1.0 as you are working on more than one plot.
; KEYWORDS:
;       X = x coordinates of the start of the arrow, either arrar or scalar
;       Y = y coordinates of the start of the arrow, either arrar or scalar
;       direction = direction of the arrow:
;         direction=0 no arrow
;         direction=1 +x, i.e. left-limit
;         direction=2 +y, i.e. lower-limit
;         direction=3 -x, i.e. right-limit
;         direction=4 -y, i.e. upper-limit
;       length = length of the arrow in normalized space. If not set
;       then the length is 0.025
;       /help = displays this information
;
; MODIFICATION HISTORY:
;       11/08/2004 Written by Eduard Westra
;-
PRO draw_limits, X, Y, direction=direction, length=length, help=help
IF keyword_set(help) THEN BEGIN & doc_library,'draw_limits' & RETURN & ENDIF
IF NOT KEYWORD_SET(length) THEN length = 0.025

IF N_ELEMENTS(X) NE N_ElEMENTS(Y) THEN MESSAGE, "X and Y are unequal in size!"
IF (N_ELEMENTS(direction) NE 1) AND (N_ELEMENTS(direction) NE N_ELEMENTS(X)) THEN MESSAGE, "direction is unequal in size to X and Y!"
IF (N_ELEMENTS(length) NE 1) AND (N_ELEMENTS(length) NE N_ELEMENTS(X)) THEN MESSAGE, "length is unequal in size to X and Y!"

idx = WHERE(direction NE 0, count)
IF count EQ 0 THEN RETURN

xx        = x[idx]
yy        = y[idx]
direction = direction[idx]
length    = length[idx]

coords = CONVERT_COORD(xx, yy, /data, /to_norm)
x0 = coords[0,*]
y0 = coords[1,*]

xflip = (!X.CRANGE[0] GT !X.CRANGE[1])
yflip = (!Y.CRANGE[0] GT !Y.CRANGE[1])

x1 = x0+(DOUBLE(direction EQ 1)-DOUBLE(direction EQ 3))*length*(xflip ? -1. : 1)
y1 = y0+(DOUBLE(direction EQ 2)-DOUBLE(direction EQ 4))*length*(yflip ? -1. : 1)

arrow, x0, y0, x1, y1, /norm
END