DEW: Data Entry Widget		Modified: Nov 2005

This widget creates one of a number of different types of "entries" or areas
where data may be entered or manipulated by the user.  It also has a built-in
text label (or title) that goes near the entry.

For example, you might have the title "Filename:" followed by an entry where
the user is expected to type in the name of a file.  Or you might have the
title "Gender:" followed by a pulldown menu where the user can select an
'M' or an 'F.'  You might also need a title "Address:" which would have a
text widget after it that 40 or so columns wide and several lines long.  All
these combinations can be created by the dew megawidget.

Dew also incorporates an optional "special function" for each entry.  This
is generally some type of pop-up window that helps the user in editing the
field (like a date selector, a calculator, etc.)  The spf is requested by
the user by right-clicking on the entry or by clicking on the title label
(which is really a button if an spf is enabled).  As you might imagine, spf's
are really only applicable to text entries.

External Procedures:
------------------------------------------
dew::dew {w args}		Creates a new dew widget
    All arguments not among those enumerated below are passed along to the
    entry widget (whatever type it may be).

Args:
    w:	The name of the new widget to create
    
Shortcuts:	type, title

Switches:
    -style	This determines the type of entry to create.  The options
    	are as follows:
    	
	ent	single line text entry (TK entry)
	mle	multi-line entry (TK text box)
	pdm	pull-down menu (TK menubutton)
		For this type, the -data argument specifies the contents
		of the menu.
	chk	check box (TK checkbutton)
	rad	list of mutually exclusive boolean options (TK radio)
	pho	bitmap (TK photo type)

    -title	The text to use for a label that will be displayed near
    	the entry (usually just to the left).

    -gmc	This specifies a geometry manager command (pack, grid, place)
	to use to place the components with the widget.  The default is:

		pack %t %e -side left -anchor n

	The %t symbol will be replaced by the name of the title.  The %e 
	symbol will be replaced by the name of the entry.  For example, you
	might place the title on top of the entry by using the following:

		-gmc {pack %t %e -side top -anchor w}

    -frame	The contents of this switch are passed through to the frame
	that underlies the dew.  For example, you might include:
    	
    		-fr {-bd 2 -relief raised -bg red}

    	to put a nice border around the dew, title and all.

    -spf	Special chooser for Button-3 (and/or PD button)	menu
	edw	Open a native text editing window on the field contents
	edi	Open an external text editor on the contents of the field
	tod	Input the current date
	mdy	Pull up a month-day spinner
	dat	Pull up a year-month-day spinner
	cal	Pull up a calendar date selector
	clc	Pull up a calculator
        fsm	Like scm but the user is forced to select a valid choice
        	from the menu.
        scm	Scrolled selector menu.  This opens a selector menu that
        	allows the user to choose one of a number of choices from a
        	list.  This differs from a pull-down menu primarily in that
        	it is searchable and can be very long.
        fnt	Standard font selector
        col	Standard color selector
        fil	Standard filename selector
        tim	Standard time selector
        	
    -spin	This specifies how to add spinner functionality to the entry.
       It is only valid for the "ent" type entry.  It consists of a dynamic argument
       list with the following switches:
       
           -type	This can be one of: int, float, enum
           -valid	For int and float types, this is a range of numbers 
           		expressed as a two-element list, like: {1 10}
           		For enum type, it is a list of valid elements, like:
           		{Jan Feb Mar Apr ...}
           -delay	How long in msec between repeats when holding buttons 
           		pressed
           -inc		Normally 1.  How many units to increment/decrement
    
    -data	This specifies a data structure that tells how a pull-down
    	menu (pdm) will operate.  It can also be used to specify how to 
    	generate a list of options for the scm and fsm special functions.
    	In the case of a pdm, the structure is a TCL list as follows:
    	
    		{
    			{tag1 {Menu item 1 description}}
    			{tag2 {Menu item 2 description}}
    			.
    			.
    			.
    			{tagN {Menu item N description}}
    		}

	Where the tag is the value the field will take on when the menu
	choice is selected and the description will be shown in the menu
	with the tag to help the user know what it means (because the tag
	is usually a bit cryptic).
	
	In the case of the spf types scm and fsm, this switch specifies
	arguments to be included when the scmenu (scrolled menu) is 
	invoked.  It can include an explicit list of choices, a database
	query which will generate the choices, etc.  For example, you might
	use something like the following:
	
		{-format {%2s %s} -eval {-eval {sql::qlist "select ..."}}
		
	See the documentation for scmenu for more details on its use.

Widget Command {widget_name command args}:
------------------------------------------
If the command argument is other than what is enumerated below, the command
is passed down to the entry widget.

Command:
    w		Return the name of the widget.
    
    title	The arguments following are passed down to the title
    	widget (typically a label).
    	
    entry	The arguments following are passed down to the entry widget.
    	This is generally redundant since the default is to pass args to the 
	underlying entry.   But is included anyway.
    	
    button	The arguments following are passed down to the spf button 
        widget.
    	
    spf		Invoke the special function for this widget.
   
    get		Return the contents of the entry widget.

    set		Set the contents of the entry widget.
