FSC_INPUTFIELD 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 DBLTOSTR from the Coyote Library:
http://www.idlcoyote.com/programs/dbltostr.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.