>

RKCW_FIELD

 NAME:
   rkcw_field

 PURPOSE:
   This widget cluster function manages a data entry field widget.
   The field consists of a label and a text widget.  rkcw_field's can
   be string fields, integer fields or floating-point fields.  The
   default is an editable string field.

 CATEGORY:
   Widget Clusters.

 CALLING SEQUENCE:
   Result = rkcw_field(Parent)

 INPUTS:
   Parent: The widget ID of the widget to be the field's parent.

 KEYWORD PARAMETERS:
   TITLE:  A string containing the text to be used as the label for the
       field.  The default is "Input Field:".

   VALUE:  The initial value in the text widget.  This value is
       automatically converted to the type set by the STRING,
       INTEGER, and FLOATING keywords described below.

   UVALUE: A user value to assign to the field cluster.  This value
       can be of any type.

   FRAME:  The width, in pixels, of a frame to be drawn around the
       entire field cluster.  The default is no frame.

RETURN_EVENTS: Set this keyword to make cluster return an event when a
        is pressed in a text field.  The default is
       not to return events.  Note that the value of the text field
       is always returned when the WIDGET_CONTROL, field, GET_VALUE=X
       command is used.

   ALL_EVENTS: Like RETURN_EVENTS but return an event whenever the
       contents of a text field have changed.

   COLUMN: Set this keyword to center the label above the text field.
       The default is to position the label to the left of the text
       field.

   ROW:    Set this keyword to position the label to the left of the text
       field.  This is the default.

   XSIZE:  An explicit horizontal size (in characters) for the text input
       area.  The default is to let the window manager size the
       widget.  Using the XSIZE keyword is not recommended.

   YSIZE:  An explicit vertical size (in lines) for the text input
       area.  The default is 1.

   STRING: Set this keyword to have the field accept only string values.
       Numbers entered in the field are converted to their string
       equivalents.  This is the default.

     FLOATING: Set this keyword to have the field accept only floating-point
       values.  Any number or string entered is converted to its
       floating-point equivalent.

      INTEGER: Set this keyword to have the field accept only integer values.
       Any number or string entered is converted to its integer
       equivalent (using FIX).  For example, if 12.5 is entered in
       this type of field, it is converted to 12.

   LONG:   Set this keyword to have the field accept only long integer
       values.  Any number or string entered is converted to its
       long integer equivalent (using LONG).

   FONT:   A string containing the name of the X Windows font to use
       for the TITLE of the field.

    FIELDFONT: A string containing the name of the X Windows font to use
       for the TEXT part of the field.

   NOEDIT: Normally, the value in the text field can be edited.  Set this
       keyword to make the field non-editable.

   TEXTID : Returns the text id of the label so that this value may be changed by
       other programs.

   EVENT_PRO : String containing the procedure to be called when an event is generated.
       The kind of events generated are determined by keywords above.

 OUTPUTS:
   This function returns the widget ID of the newly-created cluster.

 COMMON BLOCKS:
   None.

 PROCEDURE:
   Create the widgets, set up the appropriate event handlers, and return
   the widget ID of the newly-created cluster.

 EXAMPLE:
   The code below creates a main base with a field cluster attached
   to it.  The cluster accepts string input, has the title "Name:", and
   has a frame around it:

       base = WIDGET_BASE()
       field = rkcw_field(base, TITLE="Name:", /FRAME)
       WIDGET_CONTROL, base, /REALIZE

 MODIFICATION HISTORY:
   Written by: Keith R. Crosley   June 1992
           KRC, January 1993 -- Added support for LONG
                        integers.
               AB, 7 April 1993, Removed state caching.
           JWG, August 1993, Completely rewritten to make
               use of improved TEXT widget functionality
           ACY, 25 March, 1994, fix usage of FRAME keyword
                       KDB, May 1994, Initial value =0 would result
                                      in a null text field. Fixed
                                      keyword check.
           RLK, Jan 1999 added textId keyword so that the widget_text id
                could be returned for input_focus events.
           RLK, April 1999 added the ability for the compound widget to call
                an event procedure.
DISCLAIMER:  This routine has been modified from its original form as it was
              supplied by Research Systems, Inc (RSI).  As such, RSI is not responsible
              for any errors existing in this code.