% @(#)draw_line.hlq	13.1.1.2 (ESO-IPG) 11/17/98 19:27:19 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      draw_line.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, DRAW/LINE
%.PURPOSE    On-line help file for the command: DRAW/LINE
%.VERSION    1.0  04-MAY-1984 : Creation, KB
%.VERSION    1.1  22-JUL-1991 : Update, KB
%----------------------------------------------------------------
\se
SECTION./LINE
\es\co
DRAW/LINE						22-JUL-1991  KB
\oc\su
DRAW/LINE [in_spec] [coord_ref] [draw_opt] [intens] [nocurs] [key_flag]
	draw straight line in the overlay channel
\us\pu
Purpose: 
           Draw straight lines in the overlay channel.
\up\sy
Syntax:  
           DRAW/LINE [in_spec] [coord_ref] [draw_opt] [intens] [nocurs]
                     [key_flag]
\ys\pa
           in_spec = input specification for drawing start- and endpoint;
\\
                (a) CURSOR if coordinates are chosen via the cursor rectangle;
\\
                (b) name of table containing coordinates in columns labeled
                    :XSTART, :YSTART, :XEND and :YEND;
\\
                (c) x1,y1,x2,y2 defining the coords. of start and end of line
\\
                (d) name of integer keyword holding the coords, max. 40 values,
                    i.e. 10 lines, see parameter 'key_flag'
\\
                defaulted to CURSOR
\ap\pa
           coord_ref = S or F, to indicate that coordinates should be
                interpreted as screen pixels (S) or frame-based (F) as 
		frame pixels respectively world coordinates in the usual
                MIDAS syntax, only applicable for option (b) and (c);
                for option (a) and (d) always screen pixels are used;
\\
                defaulted to S (also any other input is interpreted as "S" !)
\ap\pa
           draw_opt = direction of line, only used, if cursor rectangle input:
\\
                RU for left_down to right_up, RD for left_up to right_down in
                the cursor rectangle;
\\
                defaulted to RU (also any other input is interpreted as "RU" !)
\ap\pa
           intens = color,rotation angle (in degrees) of drawing;
\\
                the line-graph is first built up from the specs and in the
                very end rotated counter-clockwise with the rotation angle;
\\
                defaulted to WHITE,0.
\ap\pa
           nocurs = no. of cursors to use, if you specify 1, only one cursor is
                used and you have to press ENTER for the start- and endpoint of
                each line - overrides the direction given in 'draw_opt';
\\
                defaulted to 2
\ap\pa
           key_flag = K(ey) or N(okey) to indicate that 'in_spec' holds the
                name of an integer keyword which contains the positions for
                up to 10 lines, the last coord. must be followed by a -1;
\\
                defaulted to N
\ap\sa
See also: 
           DRAW/SLIT, DRAW/CIRCLE, DRAW/ELLIPS, DRAW/RECTANGLE, DRAW/ARROW
\\
           DRAW/CROSS, DRAW/ANY
\as\no
Note: 
           The parameters may also be cross referenced via
\\
           INSPEC=, COOREF=, DROPT=, INTENS=, NOCURS= and KEY=
\\
           The following colors are supported (via name or number) in X11:
\\
           Red(3), Green(4), Blue(5), Yellow(6), White(2), Black(1), 
           Magenta(7), Cyan(8).
\\
           Screen pixels may be entered as absolute values (integer numbers)
           or normalized pixels (float numbers) with 0.0,0.0 the lower left
           and 1.0,1.0 the upper right corner.
\\
           If coord_ref = F, a frame must be loaded in the displayed channel.
\\
           The cursor rectangle is moved with the mouse and adjusted in size
           with the arrow keys. Use the ENTER and EXIT buttons on the mouse to
           draw or to exit.
\\
           Due to the redrawing of the cursor rectangle the endpoints of the 
           line will not have immediately the desired color, but that will be
           corrected, once you exit from the command.
\on\exs
Examples:
\ex
           DRAW/LINE
             Use cursor rectangle to define endpoints and draw a white line
             pointing to the upper right corner.
\xe\ex
           DRAW/LINE coords F ? 6,45.
             Use values from columns :xstart, :ystart, :xend, :yend of table
             `coords.tbl', interpret them as real world coordinates of the
             currently displayed frame and draw lines with yellow color;
\\
             finally rotate the lines around their center by 45.0 degrees.
\xe\ex
           DRAW/LINE 200,200,300,300 
             Draw an line from screen pixels (200,200) to (300,300).
\xe\ex
	   DRAW/LINE @200,@200,@300,@300 F
	     Draw a line from frame pixel (200,200) to (300,300)
\xe\ex
	   DRAW/LINE 100,100,100,200 F
	     Draw a line from world coordinates (100,100) to (100,200)	     
\xe \sxe