itcl/iwidgets3.0.0/doc/entryfield.n

   1 '\"
   2 '\" Copyright (c) 1995 DSC Technologies Corporation
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 '\" @(#) entryfield.n 1.21 94/12/17 16:04:44
   8 '/"
   9 .so man.macros
  10 .HS entryfield iwid
  11 .BS
  12 '\" Note:  do not modify the .SH NAME line immediately below!
  13 .SH NAME
  14 entryfield \- Create and manipulate a entry field widget
  15 .SH SYNOPSIS
  16 \fBentryfield\fI \fIpathName \fR?\fIoptions\fR?
  17 .SH "INHERITANCE"
  18 itk::Widget <- LabeledWidget <- entryfield
  19 .SH "STANDARD OPTIONS"
  20 .LP
  21 .nf
  22 .ta 4c 8c 12c
  23 \fBbackground\fR        \fBborderWidth\fR       \fBcursor\fR    \fBexportSelection\fR
  24 \fBforeground\fR        \fBhighlightColor\fR    \fBhighlightThickness\fR        \fBinsertBackground\fR
  25 \fBinsertBorderWidth\fR \fBinsertOffTime\fR     \fBinsertOnTime\fR      \fBinsertWidth\fR
  26 \fBjustify\fR   \fBrelief\fR    \fBselectBackground\fR  \fBselectBorderWidth\fR
  27 \fBselectForeground\fR  \fBtextVariable\fR      \fBwidth\fR
  28 .fi
  29 .LP
  30 See the "options" manual entry for details on the standard options.
  31 .SH "ASSOCIATED OPTIONS"
  32 .LP
  33 .nf
  34 .ta 4c 8c 12c
  35 \fBshow\fR      \fBstate\fR
  36 .fi
  37 .LP
  38 See the "entry" manual entry for details on the associated options.
  39 .SH "INHERITED OPTIONS"
  40 .LP
  41 .nf
  42 .ta 4c 8c 12c
  43 \fBdisabledForeground\fR        \fBlabelBitmap\fR       \fBlabelFont\fR \fBlabelImage\fR
  44 \fBlabelMargin\fR       \fBlabelPos\fR  \fBlabelText\fR \fBlabelVariable\fR
  45 \fBstate\fR
  46 .fi
  47 .LP
  48 See the "labeledwidget" class manual entry for details on the
  49 inherited options.
  50 .SH "WIDGET-SPECIFIC OPTIONS"
  51 .LP
  52 .nf
  53 Name:   \fBchildSitePos\fR
  54 Class:  \fBPosition\fR
  55 Command-Line Switch:    \fB-childsitepos\fR
  56 .fi
  57 .IP
  58 Specifies the position of the child site in the entry field: \fBn\fR,
  59 \fBs\fR, \fBe\fR, or \fBw\fR.  The default is e.
  60 .LP
  61 .nf
  62 Name:   \fBcommand\fR
  63 Class:  \fBCommand\fR
  64 Command-Line Switch:    \fB-command\fR
  65 .fi
  66 .IP
  67 Specifies a Tcl command to be executed upon detection of a Return key
  68 press event.
  69 .LP
  70 .nf
  71 Name:   \fBfixed\fR
  72 Class:  \fBFixed\fR
  73 Command-Line Switch:    \fB-fixed\fR
  74 .fi
  75 .IP
  76 Restrict entry to the specified number of chars.  A value of 0, which is the
  77 default, denotes no limit.  The value is the maximum number of chars the
  78 user may type into the field, regardles of field width.  For example,
  79 if the field width is set to 20 and the fixed value is 10, the user will
  80 only be able to type 10 characters into the field which is 20 characters long.
  81 .LP
  82 .nf
  83 Name:   \fBfocusCommand\fR
  84 Class:  \fBCommand\fR
  85 Command-Line Switch:    \fB-focuscommand\fR
  86 .fi
  87 .IP
  88 Specifies a Tcl command to be executed upon reception of focus.
  89 .LP
  90 .nf
  91 Name:   \fBinvalid\fR
  92 Class:  \fBCommand\fR
  93 Command-Line Switch:    \fB-invalid\fR
  94 .fi
  95 .IP
  96 Specifies a Tcl command to be executed upon determination of invalid input.
  97 The default is bell.
  98 .LP
  99 .nf
 100 Name:   \fBtextBackground\fR
 101 Class:  \fBBackground\fR
 102 Command-Line Switch:    \fB-textbackground\fR
 103 .fi
 104 .IP
 105 Background color for inside textual portion of the entry field.  The value
 106 may be given in any of the forms acceptable to \fBTk_GetColor\fR.
 107 .LP
 108 .nf
 109 Name:   \fBtextFont\fR
 110 Class:  \fBFont\fR
 111 Command-Line Switch:    \fB-textfont\fR
 112 .fi
 113 .IP
 114 Name of font to use for display of text in entryfield.  The value
 115 may be given in any of the forms acceptable to \fBTk_GetFont\fR.
 116 .LP
 117 .nf
 118 Name:   \fBvalidate\fR
 119 Class:  \fBCommand\fR
 120 Command-Line Switch:    \fB-validate\fR
 121 .fi
 122 .IP
 123 The validate option allows specification of a validation mechanism.  Standard
 124 character validation such as \fBnumeric\fR, \fBalphabetic\fR, \fBinteger\fR,
 125 \fBhexidecimal\fR, \fBreal\fR, and \fBalphanumeric\fR can be handled through
 126 the use of keywords.  Should more
 127 extensive validation be necessary, the value may contain the name of
 128 a command script.  The script should return a boolean value.  True for
 129 valid, false for invalid.  If false is returned, then the procedure
 130 associated with the invalid option will be invoked.
 131 If the validation script contains
 132 any \fB%\fR characters, then the script will not be
 133 executed directly.  Instead, a new script will be
 134 generated by replacing each \fB%\fR, and the character following
 135 it, with information from the entryfield.  The replacement
 136 depends on the character following the \fB%\fR, as defined in the
 137 list below.
 138 .TP
 139 \fB%c\fR
 140 Replaced with the current input character.
 141 .TP
 142 \fB%P\fR
 143 Replaced with the contents of the entryfield modified to include the latest
 144 keystoke.  This is equivalent to peeking at the future contents, enabling
 145 rejection prior to the update.
 146 .TP
 147 \fB%S\fR
 148 Replaced with the current contents of the entryfield prior to the latest
 149 keystroke being added.
 150 .TP
 151 \fB%W\fR
 152 Replaced with the entryfield widget pathname.
 153 .LP
 154 .BE
 155
 156 .SH DESCRIPTION
 157 .PP
 158 The \fBentryfield\fR command creates an enhanced text entry widget with an
 159 optional associated label.  Addtional options support validation and
 160 establishing a upper limit on the number of characters which may be
 161 entered in the field.
 162 .DE
 163
 164 .SH "METHODS"
 165 .PP
 166 The \fBentryfield\fR command creates a new Tcl command whose
 167 name is \fIpathName\fR.  This
 168 command may be used to invoke various
 169 operations on the widget.  It has the following general form:
 170 .DS C
 171 \fIpathName option \fR?\fIarg arg ...\fR?
 172 .DE
 173 \fIOption\fR and the \fIarg\fRs
 174 determine the exact behavior of the command.  The following
 175 commands are possible for entryfield widgets:
 176 .SH "ASSOCIATED METHODS"
 177 .LP
 178 .nf
 179 .ta 4c 8c 12c
 180 \fBdelete\fR    \fBget\fR       \fBicursor\fR   \fBindex\fR
 181 \fBinsert\fR    \fBscan\fR      \fBselection\fR \fBxview\fR
 182 .fi
 183 .LP
 184 See the "entry" manual entry for details on the associated methods.
 185 .SH "WIDGET-SPECIFIC METHODS"
 186 .TP
 187 \fIpathName \fBcget\fR \fIoption\fR
 188 Returns the current value of the configuration option given
 189 by \fIoption\fR.
 190 \fIOption\fR may have any of the values accepted by the \fBentryfield\fR
 191 command.
 192 .TP
 193 \fIpathName \fBchildsite\fR
 194 Returns the path name of the child site.
 195 .TP
 196 \fIpathName \fBclear\fR
 197 Clear entry widget
 198 .TP
 199 \fIpathName\fR \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
 200 Query or modify the configuration options of the widget.
 201 If no \fIoption\fR is specified, returns a list describing all of
 202 the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
 203 information on the format of this list).  If \fIoption\fR is specified
 204 with no \fIvalue\fR, then the command returns a list describing the
 205 one named option (this list will be identical to the corresponding
 206 sublist of the value returned if no \fIoption\fR is specified).  If
 207 one or more \fIoption\-value\fR pairs are specified, then the command
 208 modifies the given widget option(s) to have the given value(s);  in
 209 this case the command returns an empty string.
 210 \fIOption\fR may have any of the values accepted by the \fBentryfield\fR
 211 command.
 212
 213 .SH "COMPONENTS"
 214 .LP
 215 .nf
 216 Name:   \fBefchildsite\fR
 217 Class:  \fBframe\fR
 218 .fi
 219 .IP
 220 The efchildsite component is the user child site for the entry field.  See
 221 the "frame" widget manual entry for details on the efchildsite component item.
 222 .LP
 223 .nf
 224 Name:   \fBentry\fR
 225 Class:  \fBentry\fR
 226 .fi
 227 .IP
 228 The entry component provides the entry field for user text input and display.
 229 See the "entry" widget manual entry for details on the entry component item.
 230 .fi
 231
 232 .SH EXAMPLE
 233 .DS
 234  option add *textBackground white
 235
 236  proc returnCmd {} {
 237      puts stdout "Return Pressed"
 238  }
 239
 240  proc invalidCmd {} {
 241      puts stdout "Alphabetic contents invalid"
 242  }
 243
 244  entryfield .ef -command returnCmd
 245
 246  entryfield .fef -labeltext "Fixed:" -fixed 10 -width 12
 247
 248  entryfield .nef -labeltext "Numeric:" -validate numeric -width 12
 249
 250  entryfield .aef -labeltext "Alphabetic:" \\
 251     -validate alphabetic -width 12 -invalid invalidCmd
 252
 253  entryfield .pef -labeltext "Password:" \\
 254     -show \267 -width 12 -command returnCmd
 255
 256  Labeledwidget::alignlabels .ef .fef .nef .aef .pef
 257
 258  pack .ef -fill x -expand yes -padx 10 -pady 5
 259  pack .fef -fill x -expand yes -padx 10 -pady 5
 260  pack .nef -fill x -expand yes -padx 10 -pady 5
 261  pack .aef -fill x -expand yes -padx 10 -pady 5
 262  pack .pef -fill x -expand yes -padx 10 -pady 5
 263 .DE
 264 .SH AUTHOR
 265 Sue Yockey
 266 .DE
 267 Mark L. Ulferts
 268 .LP
 269 .SH KEYWORDS
 270 entryfield, widget