% @(#)label_disp.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:43:42
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      label_disp.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, LABEL/DISPLAY
%.PURPOSE    On-line help file for the command: LABEL/DISPLAY
%.VERSION    1.0  30-OCT-1989 : Creation, KB
%----------------------------------------------------------------
\se
SECTION./DISP
\es\co
LABEL/DISPLAY						19-JAN-1999  KB
\oc\su
LABEL/DISPLAY labl [position] [mode] [option] [font] [key_flag]
	write a label on the image display
\us\pu
Purpose: 
           Write a character string into the alpha-numerics or overlay channel
           of the image display.
\up\sy
Syntax:
           LABEL/DISPLAY labl [position] [mode] [option] [font] [key_flag]
\ys\pa
           labl = string of max. 80 characters, if the string contains blanks,
                the whole string has to be enclosed within double quotes (");
\\
                or
\\
                name of char. keyword containing the string(s) (see 'key_flag')
\ap\pa
           position = line and column number in screen pixels, where to write
                the string (see the Note) or
\\
                line,column,FRAME if given in frame pixels (of the currently
                displayed image) or
\\
                CURSOR, if line and column will be picked via cursor or
\\
                name of integer keyword containing the position(s);
\\ 
                defaulted to CURSOR
\ap\pa
           mode = A(lpha) or O(verlay), for writing into the alphanumeric
                memory or overlay channel;
\\
                defaulted to O for XWindow displays, to A for all others;
\\
                invalid input defaults also to O
\ap\pa
           option = color of label, if mode = OV; defaulted to white
	        with option 0 an existing label can be removed  
\ap\pa
           font = 0, 1, 2 for Normal, Large or VeryLarge text font or 3 for
                special font; 
\\
                default = 0 - this parameter is only used for X11 devices!
\ap\pa
           key_flag = K(ey) or N(okey) to indicate that 'labl' and 'position'
                hold names of a char. and integer keyword which contain the
                labels and positions;
\\
                up to 20 labels with a total max. of 200 chars. may be stored
                in the char. keyword, each label is terminated by a single
                tilde char. ("~"). The last label is terminated by two 
                consecutive tildes ("~~");
\\
                and as many line,col pairs must be stored in the integer
                keyword;
\\
                defaulted to N
\ap\see
See also:
           LABEL/ANY, CLEAR/DISPLAY, CLEAR/ALPHA, INITIALIZE/DISPLAY,
\\
           @a showfonts, @a fonttxt, @a send_mess
\ees\no
Note:    
           Important: contrary to the usual MIDAS syntax, positions are 
	   entered as line,column which corresponds to y,x!
	   
           The screen pixels are taken as absolute pixels if entered as
           integer numbers. They are taken as normalized screen pixels (with
           0.0,0.0 the lower left and 1.0,1.0 the upper right corner) when
           entered as real numbers.
\\
           Please, note an important detail with the option CURSOR:
           While additional label strings are entered, keep the cursor 
           (i.e. the mouse pointer) always in the display window, do not 
           move the mouse back into the Midas command window...!!
\\
           Also, not all special characters may be supported by the X-Font 
           chosen...
\\
           Whereas the fonts for small, medium and large sized text are fixed
           (defined with the INITIALIZE/DISPLAY command), the special font 
           used via `font'=3 can be changed dynamically:
\\
           Entering `font' < 0 is interpreted as a negative font no. of the
           font file $MID_SYSTAB/x11fonts.dat (MID_SYSTAB:x11fonts.dat in VMS).
           This font is then loaded and used for subsequent LABEL commands
           with `font'=3. 
\\
           Use "@a showfonts" for a demonstration of the available fonts.
\\
           But, when the display is refreshed only the last chosen font is used
           for all labels drawn with `font'=3 ...
\on\exs
Examples:
\ex
           LABEL/DISPLAY "My star is red" CURSOR OV yellow 1
             Use the cursor to determine the position where to put the label
             "My star is red" in the overlay channel in large letters and in
             yellow color. 
\xe\ex
           LABEL/DISPLAY in_a inputi OV ? ? keyword
             Write "GALAXY" and "Viva Midas" into the overlay channel at
             positions 20,20 and 230,100.
\\
             Keyword IN_A contains: `GALAXY~Viva Midas~~' and keyword inputi
             holds 20,20,230,100.
\xe\ex
           LABEL/DISPLAY MickeyMouse p5=2
             Write "MickeyMouse" at cursor position using the font for large
             text.
\xe\ex
           LABEL/DISPLAY MickeyMouse p5=-213
             Write "MickeyMouse" at cursor position using the font which is
             specified in line 213 of the fonts file MID_SYSTAB:x11fonts.dat.
\xe\ex
           LABEL/DISPLAY MickeyMouse @320,@20,f p5=-213
             As above but write the string at the position where the frame
             xy-pixels (20,320) of the loaded image are displayed.
\xe\ex
           LABEL/DISPLAY MickeyMouse 0.75,0.75 p5=-213
             As above but write the string at 3/4 of x- and y-size of display.
\xe\ex
           LABEL/DISPLAY MickeyMouse 0.75,0.75 p4=0 p5=-213
	     Will remove the label MickeyMouse which was created by the 
	     previous example 
\xe \sxe