# coyote: FSC_INPUTFIELD

- coyote/General Programming
- [Source code]

NAME

      FSC_INPUTFIELD

PURPOSE

      The purpose of this compound widget is to provide an alternative
      to the CW_FIELD widget offered in the IDL distribution. What has
      always bothered me about CW_FIELD is that the text widgets do not
      look editable to the users on Windows platforms. This program
      corrects that deficiency and adds some features that I think
      would be helpful. For example, you can now assign an event handler
      to the compound widget. The program is written entirely as an object.
      A companion program, COYOTE_FIELD, has much the same functionality,
      but is written as a traditional compound widget. The point of writing
      the same program in two different ways is to give you the opportunity
      to compare and contrast the two methods. I personally think there
      is no substitute for the power of object programs. :-)

AUTHOR

      FANNING SOFTWARE CONSULTING
      David Fanning, Ph.D.
      1645 Sheely Drive
      Fort Collins, CO 80526 USA
      Phone: 970-221-0438
      E-mail: david@idlcoyote.com
      Coyote's Guide to IDL Programming: http://www.idlcoyote.com/

CATEGORY

      General programming.

CALLING SEQUENCE

      objectRef = FSC_INPUTFIELD(parent, Title='X Size: ", Value=256, /IntegerValue)

INPUT PARAMETERS

      parent -- The parent widget ID of the compound widget. Required.

INPUT KEYWORDS

      Column -- Set this keyword to have the Label Widget above the Text Widget.
      CR_Only -- Set this keyword if you only want Carriage Return events. Note that no
                 events are returned unless the EVENT_PRO or EVENT_FUNC keywords are also used.
      Decimal -- Set this keyword to the number of digits to the right of the decimal
                 point in FLOATVALUE and DOUBLEVALUE numbers.
      Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
      DoubleValue -- Set this keyword if you want DOUBLE values returned.
      Event_Func -- Set this keyword to the name of an Event Function. If this
                   keyword is undefined and the Event_Pro keyword is undefined,
                   all compound widget events are handled internally and not
                   passed on to the parent widget.
      Event_Pro -- Set this keyword to the name of an Event Procedure. If this
                   keyword is undefined and the Event_Func keyword is undefined,
                   all compound widget events are handled internally and not
                   passed on to the parent widget.
      FieldFont -- The font name for the text in the Text Widget.
      FloatValue -- Set this keyword for FLOAT values.
      Focus_Events -- Set this keyword if you only want text events when the keyboard focus is
                   moved out of the text widget. Note that no events are returned unless the
                   EVENT_PRO or EVENT_FUNC keywords are also used.
      Frame -- Set this keyword to put a frame around the compound widget.
      IntegerValue -- Set this keyword for INTEGER values.
      LabelAlign -- Set this keyword to align label text. [0-center (default), 1-left, 2-right].
      LabelFont -- The font name for the text in the Label Widget.
      LabelSize -- The X screen size of the Label Widget.
      LongValue -- Set this keyword for LONG values.
      Name -- A scalar string name of the object. (default = '')
      Positive -- Set this keyword if you want only positive numbers allowed.
      Row=row -- Set this keyword to have the Label beside the Text Widget. (The default.)
      Scr_XSize -- The X screen size of the compound widget.
      Scr_YSize -- The Y screen size of the compound widget.
      StringValue -- Set this keyword for STRING values. (The default.)
      Title -- The text to go on the Label Widget.
      UValue -- A user value for any purpose.
      Value -- The "value" of the compound widget.
      XSize -- The X size of the Text Widget.
      In addition, any keyword defined for WIDGET_TEXT, but not defined here (e.g., SENSITIVE), is
      passed along without inspection to the text widget. Use of "extra" keywords is discouraged.

COMMON BLOCKS

      None.

RESTRICTIONS

      None.

EVENT STRUCTURE

      All events are handled internally unless either the Event_Pro or Event_Func
      keywords are used to assign an event handler to the compound widget. By
      default all events generated by the text widget are passed to the assigned
      event handler. If you wish to receive only Carriage Return events, set the
      CR_Only keyword.
      event = { FSC_INPUTFIELD_EVENTS, $  ; The name of the event structure.
                ID: 0L, $                 ; The ID of the compound widget's top-level base.
                TOP: 0L, $                ; The widget ID of the top-level base of the hierarchy.
                HANDLER: 0L, $            ; The event handler ID. Filled out by IDL.
                ObjRef: Obj_New(), $      ; The "self" object reference. Provided so you can call methods.
                Value: Ptr_New(), $       ; A pointer to the widget value.
                Type:""                   ; A string indicating the type of data in the VALUE field.
              }                           ; Values are "INT", "LONG", "FLOAT", "DOUBLE", or "STRING".

GETTING and SETTING VALUES

      Almost all the properties of the widget can be obtained or set via
      the object's GetProperty and SetProperty methods (described below).
      But since traditional compound widgets have the ability to get and
      set the value of the compound widget, this capability is implemented
      as special methods.
      To get the value of the field, do this: value = objectRef->Get_Value()
      To set the value of the field, so this: objectRef->Set_Value, value, /IntegerValue
      The proper keyword should be used to set the data type of the value. If a keyword
      is not used, the data type is determined from the value itself.

OBJECT PROCEDURE METHODS

      GetProperty -- This method allows various properties of the widget to be
          returned via output keywords. The keywords that are available are:
          CR_Only -- A flag, if set, means only report carriage return events.
          DataType -- The data type of the field variable.
          Decimal -- Set this keyword to the number of digits to the right of the decimal
                 point in FLOATVALUE and DOUBLEVALUE numbers.
          Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
          Event_Func -- The name of the event handler function.
          Event_Pro -- The name of the event handler function.
          Positive -- Indicates if the Positive number flag is set (1) or not (0).
          UValue -- The user value assigned to the compound widget.
          Value -- The "value" of the compound widget.
        Name -- A scalar string name of the object.
      Resize -- This method allows you to resize the compound widget's text field.
           The value parameter is an X screen size for the entire widget. The text
           widget is sized by using the value obtained from this value minus the
           X screen size of the label widget.
             objectRef->Resize, screen_xsize_value
      Set_Value -- This method allows you to set the "value" of the field. It takes
          one positional parameter, which is the value.
             objectRef->Set_Value, 5
          Keywords available are these to set the type of the data. If keywords
          are not used, the data type is determined from the value.
          DoubleValue -- Set this keyword if you want DOUBLE values returned.
          FloatValue -- Set this keyword for FLOAT values.
          IntegerValue --  Set this keyword for INTEGER values.
          LongValue -- Set this keyword for LONG values.
          StringValue -- Set this keyword for STRING values. (The default.)
      SetProperty -- This method allows various properties of the widget to be
          set via input keywords. The keywords that are available are:
          CR_Only -- Set this keyword if you only want Carriage Return events.
          Decimal -- Set this keyword to the number of digits to the right of the decimal
                 point in FLOATVALUE and DOUBLEVALUE numbers.
          Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
          DoubleValue -- Set this keyword if you want DOUBLE values returned.
          Event_Func -- Set this keyword to the name of an Event Function.
          Event_Pro -- Set this keyword to the name of an Event Procedure.
          FloatValue -- Set this keyword for FLOAT values.
          IntegerValue --  Set this keyword for INTEGER values.
          LabelSize --  The X screen size of the Label Widget.
          LongValue -- Set this keyword for LONG values.
          Name -- A scalar string name of the object. (default = '')
          Positive -- Set this keyword to indicate only positive numbers are allowed.
          Scr_XSize -- The X screen size of the text widget.
          Scr_YSize -- The Y screen size of the text widget.
          Sensitive -- Set to 1 to make the widget sensitive, and to 0 to make it insensitive.
          StringValue -- Set this keyword for STRING values. (The default.)
          Title -- The text to go on the Label Widget.
          UValue -- A user value for any purpose.
          Value -- The "value" of the compound widget.
          XSize -- The X size of the Text Widget.
      SetTabNext -- This method allows you to specify which field to go to when a TAB character
         is typed in the text widget. See the Example program below for an example of how to
         use this method.

OBJECT FUNCTIONS METHODS

      Get_Value -- Returns the "value" of the field. No parameters. Will be undefined
          if a "number" field is blank. Should be checked before using:
          IF N_Elements(objectRef->Get_Value()) NE 0 THEN Print, Value is: ', objectRef->Get_Value()
      GetID -- Returns the widget identifier of the compound widget's top-level base.
         (The first child of the parent widget.) No parameters.
      GetLabelSize -- Returns the X screen size of the label widget. No parameters.
      GetTextID -- Returns the widget identifier of the compound widget's text widget.
         No parameters.
      GetTextSize -- Returns the X screen size of the text widget. No parameters.

PRIVATE OBJECT METHODS

      Although there is really no such thing as a "private" method in IDL's
      object implementation, some methods are used internally and not meant to
      be acessed publicly. Here are a few of those methods. I list them because
      it may be these private methods are ones you wish to override in subclassed
      objects.
         MoveTab -- This method moves the focus to the widget identified in the "next" field,
           which must be set with the SetTabNext method. No parameters. Called automatically
           when a TAB character is typed in the text widget.
         Text_Events -- The main event handler method for the compound widget. All
           text widget events are processed here.
         ReturnValue -- This function method accepts a string input value and converts
           it to the type of data requested by the user.
         Validate -- This function method examines all text input and removes unwanted
           characters, depending upon the requested data type for the field. It makes it
           impossible, for example, to type alphanumeric characters in an INTEGER field.

EXAMPLE

      An example program is provided at the end of the FSC_INPUTFIELD code. To run it,
      type these commands:
         IDL> .Compile FSC_InputField
         IDL> Example

NOTES

      IDL 6.2 introduced new TAB behavior, which broke the previous TAB behavior. New TAB behavior
      is now supported, but FOCUS_EVENTS *must* be set on the widget for the new TAB events to
      behave properly. See the EXAMPLE program for examples.

DEPENDENCIES

      Requires cgDblToStr from the Coyote Library:
        http://www.idlcoyote.com/programs/cgdbltostr.pro

MODIFICATION HISTORY

      Written by: David W. Fanning, 23 NOV 1999.
      Added DECIMAL and DIGITS keywords, 2 Jan 2000, DWF.
      Changed the calling sequence to that of a function rather than an object
         creation call. This is more familiar to users of compound widgets. 4 Jan 00. DWF.
      Added GetID and Resize methods. 7 Jan 00. DWF.
      Added the Positive keyword and functionality. 12 Jan 00. DWF
      Modified (slightly) the behavior on deleting characters. 12 Jan 00. DWF.
      If a number field is blank, the Get_Value method will now return an undefined variable.
         Be sure you check this value before you use it for something! 17 Jan 00. DWF.
      Fixed a small typo: "aveDecimal" to "haveDecimal". 10 March 2000. DWF.
      Added the ability to tab between FSC_INPUTFIELD widgets with the SetTabNext,
         MoveTab, and GetTextID methods. 31 July 2000. DWF.
      Added NAME field property, a scalar string name for the object 2 AUG 2000 BT
      Added ObjRef field to the FSC_FIELD event structure and added field selection
         for the TAB events added 31 July. 7 AUG 2000. DWF
      Added GetTextSize and GetLabelSize methods for obtaining the X screen
         size of the text and label widgets, respectively. 30 Jan 2001. DWF.
      Added FOCUS_EVENTS keyword and fixed a problem with the event structure.
         Also added better error handling. 5 January 2003. DWF.
      Fixed a small problem in which input values were cast to strings inadvertently. 9 January 2004. DWF.
      Fixed a small problem with error messages and using EVENT_FUNC. 14 January 2004. DWF.
      Fixed a problem when setting ROW keyword. 23 February 2004. DWF.
      IDL 6.2 introduced new TAB behavior, which broke the previous TAB behavior. New TAB behavior
         is now supported, but FOCUS_EVENTS *must* be set for the new TAB events to behave properly.
         10 August 2005. DWF.
      Modified to covert double precision values to strings properly. 30 November 2005. DWF.
      Added POSITIVE keyword to SETPROPERTY and GETPROPERTY methods. 25 February 2006. DWF.
      Set the DYNAMIC_RESIZE keyword on the label widget. 25 February 2006. DWF.
      Added SENSITIVE keyword to SetProperty documentation. 10 November 2006. DWF.
      Fixed a small problem in which doubles were not being initialized correctly due
         to an inadvertant extra line of code. 3 July 2007. DWF.
      Fixed a small problem with input validation when the input is of BYTE type. 1 Oct 2008. DWF.
      Set the default fonts to be the current widget font, rather than the default widget font. 4 Oct 2008. DWF.
      Fixed a problem with validating a float or double value when it was written with
         exponential notation. 2 April 2010. DWF.