>

CW_UNIT_FIELD

 NAME:
       cw_unit_field

 PURPOSE:
       This is similiar to the cw_field widget in IDL. However, along with the
       data field the user also enters units of the data. The widget can be set
       up so that either the units are always fixed in the display, or they can be
       changed by the user.  This is a very useful widget for people working in an
       environment where everybody has their own favorite units.  The behaviour is
       designed to be very intuitive.  The user can  do five things in the text
       field.
               1. Type in new value and unit.
               2. Type in new value only and not change unit.
               3. Type in new unit only and not change value.
               4. Type in new value without a unit.
               5. Type in new unit without a value.
       As mentioned above, two modes exist for this widget.  "Keep" keyword set or not set.
       When the keep keyword is set, all further unit changes input by the user are
       changed back to initial units.  For example, if the widget was created with kilometers
       as the default then typing in 1 mile will cause the display to change to 1.609 km.
       KEEP KEYWORD SET MODE:
       Responses to each above items.
               1.  Number and units will be changed to default units. i.e. if default is kilometers,
                       typing in 1 nmi (nautical mile) will cause the display to change to 1.852 km.
               2.  No further action will take place
               3.      Widget will take the new entry and change it back to the default units. i.e. if
                       the entry was originally 1 km and the user changed the km to mile then the widget
                       will assume that the user wishes to change 1 mile to kilomters and display 1.609 km.
               4.  Only entering a value will cause the default unit to be displayed after pressing return.
               5.  Only entering a unit with no number will cause NaN to be displayed.
       KEEP KEYWORD NOT SET.
               1.  New units will be taken as the current default and no further action will take place.
               2.  No further action will take place.
               3.  Widget will take the new unit and change the value by the appropriate conversion factor.
                       i.e. if the original entry was 1.0 km and the user changed the unit only to mile then the
                       widget will redisplay the entry as .62137119 mi.
               4.  Only entering a value will cause the last unit used to be displayed after pressing return.
               5.  Only entering a unit with no number will cause NaN to be displayed.
   BOTH MODES:
               Entering invalid units (like furlongs) will cause the last unit to be displayed.

       THESE INSTRUCTIONS SHOULD NOT SCARE OFF DEVELOPERS! THIS IS A VERY INTUITIVE WIDGET THAT WORKS
       EXACTLY AS USERS "EXPECT" IT TO!
       This functionality can easily be extended to additional units and types.  At some point in the future
       I am going to add a rate type so that users can change between rates easily (ft/sec to km/hour for example).

 CATEGORY:
       Compound Widget

 CALLING SEQUENCE:
       Result = cw_unit_field(Parent,lots_of_keywords)

 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:". If title is equal to one space
               then no base will be created for this field.  This is useful when trying to
               get widget layouts like you want them.

       VALUE:  The initial value in the text widget.

       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.


       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.


       FONT:   A string containing the name of the platform windows font to use
               for the TITLE of the field.

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

       FORMAT : Format for the text part of the field.  If none is specified than
                a format of f5.1 is used.

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

 COMMON BLOCKS:
       None.

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

 SIDE EFFECTS:
       Reasonable error checking is done, but developers should be aware that more
       may be needed for their environment. A good example is double negative signs
       cause the program to get confused.
 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()
           dis_unit = cw_unit_field(base1,/row,value='1.0 kilom',xsize=20,ysize=1,$
           title='distance',/distance,/keep)
           WIDGET_CONTROL, base, /REALIZE

 MODIFICATION HISTORY:
       Written by:
       RLK, Ronn Kling Consulting.
       ronn@rlkling.com
       www.rlkling.com

 SHAREWARE PRICE FOR THE SOURCE CODE
 $5.00 US

PLEASE USE THE RIGHT MOUSE BUTTON TO SAVE THESE FILES.