doc/entry.n

   1 '\"
   2 '\" Copyright (c) 1990-1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
   4 '\" Copyright (c) 1996-1999 Christian Werner
   5 '\"
   6 '\" See the file "license.terms" for information on usage and redistribution
   7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   8 '\"
   9 .so man.macros
  10 .TH entry n 8.0 Ck "Ck Built-In Commands"
  11 .BS
  12 '\" Note:  do not modify the .SH NAME line immediately below!
  13 .SH NAME
  14 entry \- Create and manipulate entry widgets
  15 .SH SYNOPSIS
  16 \fBentry\fI \fIpathName \fR?\fIoptions\fR?
  17 .SH "STANDARD OPTIONS"
  18 .LP
  19 .nf
  20 .ta 4c 8c 12c
  21 \fBattributes\fR        \fBjustify\fR   \fBselectForeground\fR  \fBxScrollCommand\fR
  22 \fBbackground\fR        \fBselectAttributes\fR  \fBtakeFocus\fR
  23 \fBforeground\fR        \fBselectBackground\fR  \fBtextVariable\fR
  24 .fi
  25 .LP
  26 See the ``options'' manual entry for details on the standard options.
  27 .SH "WIDGET-SPECIFIC OPTIONS"
  28 .ta 4c
  29 .LP
  30 .nf
  31 Name:   \fBshow\fR
  32 Class:  \fBShow\fR
  33 Command-Line Switch:    \fB\-show\fR
  34 .fi
  35 .IP
  36 If this option is specified, then the true contents of the entry
  37 are not displayed in the window.
  38 Instead, each character in the entry's value will be displayed as
  39 the first character in the value of this option, such as ``*''.
  40 This is useful, for example, if the entry is to be used to enter
  41 a password.
  42 .LP
  43 .nf
  44 Name:   \fBstate\fR
  45 Class:  \fBState\fR
  46 Command-Line Switch:    \fB\-state\fR
  47 .fi
  48 .IP
  49 Specifies one of two states for the entry:  \fBnormal\fR or \fBdisabled\fR.
  50 If the entry is disabled then the value may not be changed using widget
  51 commands and no insertion cursor will be displayed, even if the input focus is
  52 in the widget.
  53 .LP
  54 .nf
  55 Name:   \fBwidth\fR
  56 Class:  \fBWidth\fR
  57 Command-Line Switch:    \fB\-width\fR
  58 .fi
  59 .IP
  60 Specifies an integer value indicating the desired width of the entry window,
  61 in screen columns. If the value is less than or equal to zero, the widget
  62 picks a size just large enough to hold its current text. The default width
  63 is 16.
  64 .BE
  65
  66 .SH DESCRIPTION
  67 .PP
  68 The \fBentry\fR command creates a new window (given by the
  69 \fIpathName\fR argument) and makes it into an entry widget.
  70 Additional options, described above, may be specified on the
  71 command line or in the option database
  72 to configure aspects of the entry such as its colors and attributes.
  73 The \fBentry\fR command returns its
  74 \fIpathName\fR argument.  At the time this command is invoked,
  75 there must not exist a window named \fIpathName\fR, but
  76 \fIpathName\fR's parent must exist.
  77 .PP
  78 An entry is a widget that displays a one-line text string and
  79 allows that string to be edited using widget commands described below, which
  80 are typically bound to keystrokes and mouse actions.
  81 When first created, an entry's string is empty.
  82 A portion of the entry may be selected as described below.
  83 Entries also observe the standard Ck rules for dealing with the
  84 input focus.  When an entry has the input focus it displays an
  85 \fIinsertion cursor\fR to indicate where new characters will be
  86 inserted.
  87 .PP
  88 Entries are capable of displaying strings that are too long to
  89 fit entirely within the widget's window.  In this case, only a
  90 portion of the string will be displayed;  commands described below
  91 may be used to change the view in the window.  Entries use
  92 the standard \fBxScrollCommand\fR mechanism for interacting with
  93 scrollbars (see the description of the \fBxScrollCommand\fR option
  94 for details).
  95
  96 .SH "WIDGET COMMAND"
  97 .PP
  98 The \fBentry\fR command creates a new Tcl command whose
  99 name is \fIpathName\fR.  This
 100 command may be used to invoke various
 101 operations on the widget.  It has the following general form:
 102 .DS C
 103 \fIpathName option \fR?\fIarg arg ...\fR?
 104 .DE
 105 \fIOption\fR and the \fIarg\fRs
 106 determine the exact behavior of the command.
 107 .PP
 108 Many of the widget commands for entries take one or more indices as
 109 arguments.  An index specifies a particular character in the entry's
 110 string, in any of the following ways:
 111 .TP 12
 112 \fInumber\fR
 113 Specifies the character as a numerical index, where 0 corresponds
 114 to the first character in the string.
 115 .TP 12
 116 \fBanchor\fR
 117 Indicates the anchor point for the selection, which is set with the
 118 \fBselect from\fR and \fBselect adjust\fR widget commands.
 119 .TP 12
 120 \fBend\fR
 121 Indicates the character just after the last one in the entry's string.
 122 This is equivalent to specifying a numerical index equal to the length
 123 of the entry's string.
 124 .TP 12
 125 \fBinsert\fR
 126 Indicates the character adjacent to and immediately following the
 127 insertion cursor.
 128 .TP 12
 129 \fBsel.first\fR
 130 Indicates the first character in the selection.  It is an error to
 131 use this form if the selection isn't in the entry window.
 132 .TP 12
 133 \fBsel.last\fR
 134 Indicates the character just after the last one in the selection.
 135 It is an error to use this form if the selection isn't in the
 136 entry window.
 137 .TP 12
 138 \fB@\fInumber\fR
 139 In this form, \fInumber\fR is treated as an x-coordinate in the
 140 entry's window;  the character spanning that x-coordinate is used.
 141 For example, ``\fB@0\fR'' indicates the left-most character in the
 142 window.
 143 .LP
 144 Abbreviations may be used for any of the forms above, e.g. ``\fBe\fR''
 145 or ``\fBsel.f\fR''.  In general, out-of-range indices are automatically
 146 rounded to the nearest legal value.
 147 .PP
 148 The following commands are possible for entry widgets:
 149 .TP
 150 \fIpathName \fBcget\fR \fIoption\fR
 151 Returns the current value of the configuration option given
 152 by \fIoption\fR.
 153 \fIOption\fR may have any of the values accepted by the \fBentry\fR
 154 command.
 155 .TP
 156 \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
 157 Query or modify the configuration options of the widget.
 158 If no \fIoption\fR is specified, returns a list describing all of
 159 the available options for \fIpathName\fR. If \fIoption\fR is specified
 160 with no \fIvalue\fR, then the command returns a list describing the
 161 one named option (this list will be identical to the corresponding
 162 sublist of the value returned if no \fIoption\fR is specified).  If
 163 one or more \fIoption\-value\fR pairs are specified, then the command
 164 modifies the given widget option(s) to have the given value(s);  in
 165 this case the command returns an empty string.
 166 \fIOption\fR may have any of the values accepted by the \fBentry\fR
 167 command.
 168 .TP
 169 \fIpathName \fBdelete \fIfirst \fR?\fIlast\fR?
 170 Delete one or more elements of the entry.
 171 \fIFirst\fR is the index of the first character to delete, and
 172 \fIlast\fR is the index of the character just after the last
 173 one to delete.
 174 If \fIlast\fR isn't specified it defaults to \fIfirst\fR+1,
 175 i.e. a single character is deleted.
 176 This command returns an empty string.
 177 .TP
 178 \fIpathName \fBget\fR
 179 Returns the entry's string.
 180 .TP
 181 \fIpathName \fBicursor \fIindex\fR
 182 Arrange for the insertion cursor to be displayed just before the character
 183 given by \fIindex\fR.  Returns an empty string.
 184 .TP
 185 \fIpathName \fBindex\fI index\fR
 186 Returns the numerical index corresponding to \fIindex\fR.
 187 .TP
 188 \fIpathName \fBinsert \fIindex string\fR
 189 Insert the characters of \fIstring\fR just before the character
 190 indicated by \fIindex\fR.  Returns an empty string.
 191 .TP
 192 \fIpathName \fBselection \fIoption arg\fR
 193 This command is used to adjust the selection within an entry.  It
 194 has several forms, depending on \fIoption\fR:
 195 .RS
 196 .TP
 197 \fIpathName \fBselection adjust \fIindex\fR
 198 Locate the end of the selection nearest to the character given by
 199 \fIindex\fR, and adjust that end of the selection to be at \fIindex\fR
 200 (i.e including but not going beyond \fIindex\fR).  The other
 201 end of the selection is made the anchor point for future
 202 \fBselect to\fR commands.  If the selection
 203 isn't currently in the entry, then a new selection is created to
 204 include the characters between \fIindex\fR and the most recent
 205 selection anchor point, inclusive.
 206 Returns an empty string.
 207 .TP
 208 \fIpathName \fBselection clear\fR
 209 Clear the selection if it is currently in this widget.  If the
 210 selection isn't in this widget then the command has no effect.
 211 Returns an empty string.
 212 .TP
 213 \fIpathName \fBselection from \fIindex\fR
 214 Set the selection anchor point to just before the character
 215 given by \fIindex\fR.  Doesn't change the selection.
 216 Returns an empty string.
 217 .TP
 218 \fIpathName \fBselection present\fR
 219 Returns 1 if there is are characters selected in the entry,
 220 0 if nothing is selected.
 221 .TP
 222 \fIpathName \fBselection range \fIstart\fR \fIend\fR
 223 Sets the selection to include the characters starting with
 224 the one indexed by \fIstart\fR and ending with the one just
 225 before \fIend\fR.
 226 If \fIend\fR refers to the same character as \fIstart\fR or an
 227 earlier one, then the entry's selection is cleared.
 228 .TP
 229 \fIpathName \fBselection to \fIindex\fR
 230 If \fIindex\fR is before the anchor point, set the selection
 231 to the characters from \fIindex\fR up to but not including
 232 the anchor point.
 233 If \fIindex\fR is the same as the anchor point, do nothing.
 234 If \fIindex\fR is after the anchor point, set the selection
 235 to the characters from the anchor point up to but not including
 236 \fIindex\fR.
 237 The anchor point is determined by the most recent \fBselect from\fR
 238 or \fBselect adjust\fR command in this widget.
 239 If the selection isn't in this widget then a new selection is
 240 created using the most recent anchor point specified for the widget.
 241 Returns an empty string.
 242 .RE
 243 .TP
 244 \fIpathName \fBxview \fIargs\fR
 245 This command is used to query and change the horizontal position of the
 246 text in the widget's window.  It can take any of the following
 247 forms:
 248 .RS
 249 .TP
 250 \fIpathName \fBxview\fR
 251 Returns a list containing two elements.
 252 Each element is a real fraction between 0 and 1;  together they describe
 253 the horizontal span that is visible in the window.
 254 For example, if the first element is .2 and the second element is .6,
 255 20% of the entry's text is off-screen to the left, the middle 40% is visible
 256 in the window, and 40% of the text is off-screen to the right.
 257 These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR
 258 option.
 259 .TP
 260 \fIpathName \fBxview\fR \fIindex\fR
 261 Adjusts the view in the window so that the character given by \fIindex\fR
 262 is displayed at the left edge of the window.
 263 .TP
 264 \fIpathName \fBxview moveto\fI fraction\fR
 265 Adjusts the view in the window so that the character \fIfraction\fR of the
 266 way through the text appears at the left edge of the window.
 267 \fIFraction\fR must be a fraction between 0 and 1.
 268 .TP
 269 \fIpathName \fBxview scroll \fInumber what\fR
 270 This command shifts the view in the window left or right according to
 271 \fInumber\fR and \fIwhat\fR.
 272 \fINumber\fR must be an integer.
 273 \fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation
 274 of one of these.
 275 If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by
 276 \fInumber\fR average-width characters on the display;  if it is
 277 \fBpages\fR then the view adjusts by \fInumber\fR screenfuls.
 278 If \fInumber\fR is negative then characters farther to the left
 279 become visible;  if it is positive then characters farther to the right
 280 become visible.
 281 .RE
 282
 283 .SH "DEFAULT BINDINGS"
 284 .PP
 285 Ck automatically creates class bindings for entries that give them
 286 the following default behavior.
 287 .IP [1]
 288 Clicking mouse button 1 positions the insertion cursor
 289 just before the character underneath the mouse cursor, sets the
 290 input focus to this widget, and clears any selection in the widget.
 291 .IP [2]
 292 If any normal printing characters are typed in an entry, they are
 293 inserted at the point of the insertion cursor.
 294 .IP [3]
 295 The Left and Right keys move the insertion cursor one character to the
 296 left or right;  they also clear any selection in the entry and set
 297 the selection anchor.
 298 Control-b and Control-f behave the same as Left and Right, respectively.
 299 .IP [4]
 300 The Home key, or Control-a, will move the insertion cursor to the
 301 beginning of the entry and clear any selection in the entry.
 302 .IP [5]
 303 The End key, or Control-e, will move the insertion cursor to the
 304 end of the entry and clear any selection in the entry.
 305 .IP [6]
 306 The Select key sets the selection anchor to the position
 307 of the insertion cursor. It doesn't affect the current selection.
 308 .IP [7]
 309 The Delete key deletes the selection, if there is one in the entry.
 310 If there is no selection, it deletes the character to the right of
 311 the insertion cursor.
 312 .IP [8]
 313 The BackSpace key and Control-h delete the selection, if there is one
 314 in the entry.
 315 If there is no selection, it deletes the character to the left of
 316 the insertion cursor.
 317 .IP [9]
 318 Control-d deletes the character to the right of the insertion cursor.
 319 .IP [10]
 320 Control-k deletes all the characters to the right of the insertion
 321 cursor.
 322 .IP [11]
 323 Control-t reverses the order of the two characters to the right of
 324 the insertion cursor.
 325 .PP
 326 If the entry is disabled using the \fB\-state\fR option, then the entry's
 327 view can still be adjusted and text in the entry can still be selected,
 328 but no insertion cursor will be displayed and no text modifications will
 329 take place.
 330 .PP
 331 The behavior of entries can be changed by defining new bindings for
 332 individual widgets or by redefining the class bindings.
 333
 334 .SH KEYWORDS
 335 entry, widget