# iwidgets2.2.0 User Commands - entryfield

##

## NAME

         entryfield - Create and manipulate a entry field widget

## SYNOPSIS

         entryfield pathName ?options?

## INHERITANCE

         itk::Widget <- LabeledWidget <- entryfield

## STANDARD OPTIONS

         background      borderWidth    cursor          exportSelection
         foreground      highlightColor highlightThicknessinsertBackground
         insertBorderWidth              insertOffTime   insertOnTimeinsertWidth
         justify         relief         selectBackgroundselectBorderWidth
         selectForeground               textVariable    width

         See the "options" manual entry for details on  the  standard
         options.

## ASSOCIATED OPTIONS

         show            state

         See the "entry" manual entry for details on  the  associated
         options.

## INHERITED OPTIONS

         labelBitmap     labelFont      labelImage      labelMargin
         labelPos        labelText      labelVariable

         See the "labeledwidget" class manual entry  for  details  on
         the inherited options.

## WIDGET-SPECIFIC OPTIONS

         Name:           childSitePos
         Class:          Position
         Command-Line Switch:           -childsitepos

              Specifies the position of the child site in  the  entry
              field: n, s, e, or w.  The default is e.

         Name:           command
         Class:          Command
         Command-Line Switch:           -command

              Specifies a Tcl command to be executed  upon  detection
              of a Return key press event.

         Name:           fixed
         Class:          Fixed
         Command-Line Switch:           -fixed
              Restrict entry to the specified  number  of  chars.   A
              value  of  0,  which  is the default, denotes no limit.
              The value is the maximum number of chars the  user  may
              type  into  the  field,  regardles of field width.  For
              example, if the field width is set to 20 and the  fixed
              value  is  10,  the  user  will only be able to type 10
              characters into the field which is 20 characters long.

         Name:           focusCommand
         Class:          Command
         Command-Line Switch:           -focuscommand

              Specifies a Tcl command to be executed  upon  reception
              of focus.

         Name:           invalid
         Class:          Command
         Command-Line Switch:           -invalid

              Specifies a Tcl command to be executed upon  determina-
              tion of invalid input.  The default is bell.

         Name:           textBackground
         Class:          Background
         Command-Line Switch:           -textbackground

              Background color for  inside  textual  portion  of  the
              entry  field.   The  value  may  be given in any of the
              forms acceptable to Tk_GetColor.

         Name:           textFont
         Class:          Font
         Command-Line Switch:           -textfont

              Name of font to use for display of text in  entryfield.
              The  value  may be given in any of the forms acceptable
              to Tk_GetFont.

         Name:           validate
         Class:          Command
         Command-Line Switch:           -validate

              The validate option allows specification of  a  valida-
              tion  mechanism.  Standard character validation such as
              numeric, alphabetic, integer,  hexidecimal,  real,  and
              alphanumeric  can  be  handled  through the use of key-
              words.  Should more extensive validation be  necessary,
              the  value  may  contain  the name of a command script.
              The script should return a  boolean  value.   True  for
              valid,  false  for invalid.  If false is returned, then
              the procedure associated with the invalid  option  will
              be  invoked.   If  the validation script contains any %
              characters,  then  the  script  will  not  be  executed
              directly.   Instead,  a new script will be generated by
              replacing each %, and the character following it,  with
              information   from  the  entryfield.   The  replacement
              depends on the character following the %, as defined in
              the list below.

         %c   Replaced with the current input character.

         %P   Replaced with the contents of the  entryfield  modified
              to  include the latest keystoke.  This is equivalent to
              peeking at  the  future  contents,  enabling  rejection
              prior to the update.

         %S   Replaced with the current contents  of  the  entryfield
              prior to the latest keystroke being added.

         %W   Replaced with the entryfield widget pathname.

##

## DESCRIPTION

         The entryfield command creates an enhanced text entry widget
         with  an  optional associated label.  Addtional options sup-
         port validation and establishing a upper limit on the number
         of characters which may be entered in the field.

## METHODS

         The entryfield command creates a new Tcl command whose  name
         is  pathName.   This  command  may be used to invoke various
         operations on the widget.   It  has  the  following  general
         form:

              pathName option ?arg arg ...?

         Option and the args determine the exact behavior of the com-
         mand.   The  following  commands are possible for entryfield
         widgets:

## ASSOCIATED METHODS

         delete          get            icursor         index
         insert          scan           selection       xview

         See the "entry" manual entry for details on  the  associated
         methods.

## WIDGET-SPECIFIC METHODS

         pathName cget option
              Returns the current value of the  configuration  option
              given  by  option.   Option  may have any of the values
              accepted by the entryfield command.

         pathName childsite
              Returns the path name of the child site.

         pathName clear
              Clear entry widget

         pathName configure ?option? ?value option value ...?
              Query  or  modify  the  configuration  options  of  the
              widget.   If  no  option  is  specified, returns a list
              describing all of the available  options  for  pathName
              (see  Tk_ConfigureInfo for information on the format of
              this list).  If option is specified with no value, then
              the  command  returns  a  list describing the one named
              option (this list will be identical to the  correspond-
              ing  sublist  of  the  value  returned  if no option is
              specified).  If one or more  option - value  pairs  are
              specified,  then  the command modifies the given widget
              option(s) to have the given value(s);  in this case the
              command  returns  an empty string.  Option may have any
              of the values accepted by the entryfield command.

## COMPONENTS

         Name:           efchildsite
         Class:          frame

              The efchildsite component is the user  child  site  for
              the  entry  field.  See the "frame" widget manual entry
              for details on the efchildsite component item.

         Name:           entry
         Class:          entry

              The entry component provides the entry field  for  user
              text  input and display.  See the "entry" widget manual
              entry for details on the entry component item.

## EXAMPLE

               option add *textBackground white

               proc returnCmd {} {
                   puts stdout "Return Pressed"
               }

               proc invalidCmd {} {
                   puts stdout "Alphabetic contents invalid"
               }

               entryfield .ef -command returnCmd

               entryfield .fef -labeltext "Fixed:" -fixed 10 -width 12

               entryfield .nef -labeltext "Numeric:" -validate numeric -width 12

               entryfield .aef -labeltext "Alphabetic:" \
                  -validate alphabetic -width 12 -invalid invalidCmd

               entryfield .pef -labeltext "Password:" \
                  -show 267 -width 12 -command returnCmd

               LabeledWidget::alignLabels .ef .fef .nef .aef .pef

               pack .ef -fill x -expand yes -padx 10 -pady 5
               pack .fef -fill x -expand yes -padx 10 -pady 5
               pack .nef -fill x -expand yes -padx 10 -pady 5
               pack .aef -fill x -expand yes -padx 10 -pady 5
               pack .pef -fill x -expand yes -padx 10 -pady 5

## AUTHOR

         Sue Yockey

         Mark L. Ulferts

## KEYWORDS

         entryfield, widget