Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "ENTRY 1" | |
132 | .TH ENTRY 1 "2000-12-30" "perl v5.8.0" "User Contributed Perl Documentation" | |
133 | .SH "NAME" | |
134 | Tk::Entry \- Create and manipulate Entry widgets | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | \&\ \fI$entry\fR = \fI$parent\fR\->\fBEntry\fR(?\fIoptions\fR?); | |
138 | .SH "STANDARD OPTIONS" | |
139 | .IX Header "STANDARD OPTIONS" | |
140 | \&\fB\-background\fR \fB\-highlightbackground\fR \fB\-insertontime\fR \fB\-selectforeground\fR | |
141 | \&\fB\-borderwidth\fR \fB\-highlightcolor\fR \fB\-insertwidth\fR \fB\-takefocus\fR | |
142 | \&\fB\-cursor\fR \fB\-highlightthickness\fR \fB\-justify\fR \fB\-textvariable\fR | |
143 | \&\fB\-exportselection\fR \fB\-insertbackground\fR \fB\-relief\fR \fB\-xscrollcommand\fR | |
144 | \&\fB\-font\fR \fB\-insertborderwidth\fR \fB\-selectbackground\fR | |
145 | \&\fB\-foreground\fR \fB\-insertofftime\fR \fB\-selectborderwidth\fR | |
146 | .SH "WIDGET-SPECIFIC OPTIONS" | |
147 | .IX Header "WIDGET-SPECIFIC OPTIONS" | |
148 | .IP "Name: \fBinvalidCommand\fR" 4 | |
149 | .IX Item "Name: invalidCommand" | |
150 | .PD 0 | |
151 | .IP "Class: \fBInvalidCommand\fR" 4 | |
152 | .IX Item "Class: InvalidCommand" | |
153 | .IP "Switch: \fB\-invalidcommand\fR" 4 | |
154 | .IX Item "Switch: -invalidcommand" | |
155 | .IP "Alias: \fB\-invcmd\fR" 4 | |
156 | .IX Item "Alias: -invcmd" | |
157 | .PD | |
158 | Specifies a script to eval when \fBvalidateCommand\fR returns 0. | |
159 | Setting it to <undef> disables this feature (the default). The best use | |
160 | of this option is to set it to \fIbell\fR. See \fBValidation\fR | |
161 | below for more information. | |
162 | .IP "Name: \fBshow\fR" 4 | |
163 | .IX Item "Name: show" | |
164 | .PD 0 | |
165 | .IP "Class: \fBShow\fR" 4 | |
166 | .IX Item "Class: Show" | |
167 | .IP "Switch: \fB\-show\fR" 4 | |
168 | .IX Item "Switch: -show" | |
169 | .PD | |
170 | If this option is specified, then the true contents of the entry | |
171 | are not displayed in the window. | |
172 | Instead, each character in the entry's value will be displayed as | |
173 | the first character in the value of this option, such as ``*''. | |
174 | This is useful, for example, if the entry is to be used to enter | |
175 | a password. | |
176 | If characters in the entry are selected and copied elsewhere, the | |
177 | information copied will be what is displayed, not the true contents | |
178 | of the entry. | |
179 | .IP "Name: \fBstate\fR" 4 | |
180 | .IX Item "Name: state" | |
181 | .PD 0 | |
182 | .IP "Class: \fBState\fR" 4 | |
183 | .IX Item "Class: State" | |
184 | .IP "Switch: \fB\-state\fR" 4 | |
185 | .IX Item "Switch: -state" | |
186 | .PD | |
187 | Specifies one of two states for the entry: \fBnormal\fR or \fBdisabled\fR. | |
188 | If the entry is disabled then the value may not be changed using widget | |
189 | methods and no insertion cursor will be displayed, even if the input focus is | |
190 | in the widget. | |
191 | .IP "Name: \fBvalidate\fR" 4 | |
192 | .IX Item "Name: validate" | |
193 | .PD 0 | |
194 | .IP "Class: \fBValidate\fR" 4 | |
195 | .IX Item "Class: Validate" | |
196 | .IP "Switch: \fB\-validate\fR" 4 | |
197 | .IX Item "Switch: -validate" | |
198 | .PD | |
199 | Specifies the mode in which validation should operate: \fBnone\fR, | |
200 | \&\fBfocus\fR, \fBfocusin\fR, \fBfocusout\fR, \fBkey\fR, or \fBall\fR. | |
201 | It defaults to \fBnone\fR. When you want validation, you must explicitly | |
202 | state which mode you wish to use. See \fBValidation\fR below for more. | |
203 | .IP "Name: \fBvalidateCommand\fR" 4 | |
204 | .IX Item "Name: validateCommand" | |
205 | .PD 0 | |
206 | .IP "Class: \fBValidateCommand\fR" 4 | |
207 | .IX Item "Class: ValidateCommand" | |
208 | .IP "Switch: \fB\-validatecommand\fR" 4 | |
209 | .IX Item "Switch: -validatecommand" | |
210 | .IP "Alias: \fB\-vcmd\fR" 4 | |
211 | .IX Item "Alias: -vcmd" | |
212 | .PD | |
213 | Specifies a script to eval when you want to validate the input into | |
214 | the entry widget. Setting it to \f(CW\*(C`undef\*(C'\fR disables this feature (the default). | |
215 | This command must return a valid boolean value. If it returns 0 (or | |
216 | the valid boolean equivalent) then it means you reject the new edition | |
217 | and it will not occur and the \fBinvalidCommand\fR will be evaluated if it | |
218 | is set. If it returns 1, then the new edition occurs. | |
219 | See \fBValidation\fR below for more information. | |
220 | .IP "Name: \fBwidth\fR" 4 | |
221 | .IX Item "Name: width" | |
222 | .PD 0 | |
223 | .IP "Class: \fBWidth\fR" 4 | |
224 | .IX Item "Class: Width" | |
225 | .IP "Switch: \fB\-width\fR" 4 | |
226 | .IX Item "Switch: -width" | |
227 | .PD | |
228 | Specifies an integer value indicating the desired width of the entry window, | |
229 | in average-size characters of the widget's font. | |
230 | If the value is less than or equal to zero, the widget picks a | |
231 | size just large enough to hold its current text. | |
232 | .SH "DESCRIPTION" | |
233 | .IX Header "DESCRIPTION" | |
234 | The \fBEntry\fR method creates a new window (given by the | |
235 | \&\f(CW$entry\fR argument) and makes it into an entry widget. | |
236 | Additional options, described above, may be specified on the | |
237 | command line or in the option database | |
238 | to configure aspects of the entry such as its colors, font, | |
239 | and relief. The \fBentry\fR command returns its | |
240 | \&\f(CW$entry\fR argument. At the time this command is invoked, | |
241 | there must not exist a window named \f(CW$entry\fR, but | |
242 | \&\f(CW$entry\fR's parent must exist. | |
243 | .PP | |
244 | An entry is a widget that displays a one-line text string and | |
245 | allows that string to be edited using methods described below, which | |
246 | are typically bound to keystrokes and mouse actions. | |
247 | When first created, an entry's string is empty. | |
248 | A portion of the entry may be selected as described below. | |
249 | If an entry is exporting its selection (see the \fBexportSelection\fR | |
250 | option), then it will observe the standard X11 protocols for handling the | |
251 | selection; entry selections are available as type \fB\s-1STRING\s0\fR. | |
252 | Entries also observe the standard Tk rules for dealing with the | |
253 | input focus. When an entry has the input focus it displays an | |
254 | \&\fIinsertion cursor\fR to indicate where new characters will be | |
255 | inserted. | |
256 | .PP | |
257 | Entries are capable of displaying strings that are too long to | |
258 | fit entirely within the widget's window. In this case, only a | |
259 | portion of the string will be displayed; methods described below | |
260 | may be used to change the view in the window. Entries use | |
261 | the standard \fBxScrollCommand\fR mechanism for interacting with | |
262 | scrollbars (see the description of the \fB\-xscrollcommand\fR option | |
263 | for details). They also support scanning, as described below. | |
264 | .SH "VALIDATION" | |
265 | .IX Header "VALIDATION" | |
266 | Validation of entry widgets is derived from part of the patch written by | |
267 | jhobbs@cs.uoregon.edu. This works by setting the \fBvalidateCommand\fR | |
268 | option to a callback which will be evaluated according to the \fBvalidate\fR | |
269 | option as follows: | |
270 | .IP "\fBnone\fR" 4 | |
271 | .IX Item "none" | |
272 | Default. This means no validation will occur. | |
273 | .IP "\fBfocus\fR" 4 | |
274 | .IX Item "focus" | |
275 | \&\fBvalidateCommand\fR will be called when the entry receives or | |
276 | loses focus. | |
277 | .IP "\fBfocusin\fR" 4 | |
278 | .IX Item "focusin" | |
279 | \&\fBvalidateCommand\fR will be called when the entry receives focus. | |
280 | .IP "\fBfocusout\fR" 4 | |
281 | .IX Item "focusout" | |
282 | \&\fBvalidateCommand\fR will be called when the entry loses focus. | |
283 | .IP "\fBkey\fR" 4 | |
284 | .IX Item "key" | |
285 | \&\fBvalidateCommand\fR will be called when the entry is edited. | |
286 | .IP "\fBall\fR" 4 | |
287 | .IX Item "all" | |
288 | \&\fBvalidateCommand\fR will be called for all above conditions. | |
289 | .PP | |
290 | The \fBvalidateCommand\fR and \fBinvalidCommand\fR are called with the following | |
291 | arguments: | |
292 | .IP "\(bu The proposed value of the entry. If you are configuring the entry widget to have a new textvariable, this will be the value of that textvariable." 4 | |
293 | .IX Item "The proposed value of the entry. If you are configuring the entry widget to have a new textvariable, this will be the value of that textvariable." | |
294 | .PD 0 | |
295 | .ie n .IP "\(bu The characters to be added (or deleted). This will be ""undef""\fR if validation is due to focus, explcit call to validate or if change is due to \f(CW""\-textvariable"" changing." 4 | |
296 | .el .IP "\(bu The characters to be added (or deleted). This will be \f(CWundef\fR if validation is due to focus, explcit call to validate or if change is due to \f(CW\-textvariable\fR changing." 4 | |
297 | .IX Item "The characters to be added (or deleted). This will be undef if validation is due to focus, explcit call to validate or if change is due to -textvariable changing." | |
298 | .IP "\(bu The current value of entry i.e. before the proposed change." 4 | |
299 | .IX Item "The current value of entry i.e. before the proposed change." | |
300 | .IP "\(bu index of char string to be added/deleted, if any. \-1 otherwise" 4 | |
301 | .IX Item "index of char string to be added/deleted, if any. -1 otherwise" | |
302 | .IP "\(bu type of action. 1 == \s-1INSERT\s0, 0 == \s-1DELETE\s0, \-1 if it's a forced validation or textvariable validation" 4 | |
303 | .IX Item "type of action. 1 == INSERT, 0 == DELETE, -1 if it's a forced validation or textvariable validation" | |
304 | .PD | |
305 | .PP | |
306 | In general, the \fBtextVariable\fR and \fBvalidateCommand\fR can be | |
307 | dangerous to mix. If you try set the \fBtextVariable\fR | |
308 | to something that the \fBvalidateCommand\fR will not accept it will | |
309 | be set back to the value of the entry widget. | |
310 | Using the \fBtextVariable\fR for read-only purposes will never cause problems. | |
311 | .PP | |
312 | The \fBvalidateCommand\fR will turn itself off by setting | |
313 | \&\fBvalidate\fR to \fBnone\fR when an error occurs, for example | |
314 | when the \fBvalidateCommand\fR or \fBinvalidCommand\fR encounters | |
315 | an error in its script while evaluating, or | |
316 | \&\fBvalidateCommand\fR does not return a valid boolean value. | |
317 | .PP | |
318 | With the perl/Tk version \fBvalidate\fR option is supposed to be | |
319 | \&\*(L"suspended\*(R" while executing the \fBvalidateCommand\fR or the \fBinvalidCommand\fR. | |
320 | This is experimental but in theory either callback can \*(L"correct\*(R" the | |
321 | value of the widget, and override the proposed change. (\fBvalidateCommand\fR | |
322 | should still return false to inhibit the change from happening when | |
323 | it returns.) | |
324 | .SH "WIDGET METHODS" | |
325 | .IX Header "WIDGET METHODS" | |
326 | The \fBEntry\fR method creates a widget object. | |
327 | This object supports the \fBconfigure\fR and \fBcget\fR methods | |
328 | described in Tk::options which can be used to enquire and | |
329 | modify the options described above. | |
330 | The widget also inherits all the methods provided by the generic | |
331 | Tk::Widget class. | |
332 | .PP | |
333 | Many of the additional methods for entries take one or more indices as | |
334 | arguments. An index specifies a particular character in the entry's | |
335 | string, in any of the following ways: | |
336 | .IP "\fInumber\fR" 4 | |
337 | .IX Item "number" | |
338 | Specifies the character as a numerical index, where 0 corresponds | |
339 | to the first character in the string. | |
340 | .IP "\fBanchor\fR" 4 | |
341 | .IX Item "anchor" | |
342 | Indicates the anchor point for the selection, which is set with the | |
343 | \&\fBselectionFrom\fR and \fBselectionAdjust\fR methods. | |
344 | .IP "\fBend\fR" 4 | |
345 | .IX Item "end" | |
346 | Indicates the character just after the last one in the entry's string. | |
347 | This is equivalent to specifying a numerical index equal to the length | |
348 | of the entry's string. | |
349 | .IP "\fBinsert\fR" 4 | |
350 | .IX Item "insert" | |
351 | Indicates the character adjacent to and immediately following the | |
352 | insertion cursor. | |
353 | .IP "\fBsel.first\fR" 4 | |
354 | .IX Item "sel.first" | |
355 | Indicates the first character in the selection. It is an error to | |
356 | use this form if the selection isn't in the entry window. | |
357 | .IP "\fBsel.last\fR" 4 | |
358 | .IX Item "sel.last" | |
359 | Indicates the character just after the last one in the selection. | |
360 | It is an error to use this form if the selection isn't in the | |
361 | entry window. | |
362 | .IP "\fB@\fR\fInumber\fR" 4 | |
363 | .IX Item "@number" | |
364 | In this form, \fInumber\fR is treated as an x\-coordinate in the | |
365 | entry's window; the character spanning that x\-coordinate is used. | |
366 | For example, ``\fB@0\fR'' indicates the left-most character in the | |
367 | window. | |
368 | .PP | |
369 | Abbreviations may be used for any of the forms above, e.g. ``\fBe\fR'' | |
370 | or ``\fBsel.f\fR''. In general, out-of-range indices are automatically | |
371 | rounded to the nearest legal value. | |
372 | .PP | |
373 | The following additional methods are available for entry widgets: | |
374 | .IP "\fI$entry\fR\->\fBbbox\fR(\fIindex\fR)" 4 | |
375 | .IX Item "$entry->bbox(index)" | |
376 | Returns a list of four numbers describing the bounding box of the | |
377 | character given by \fIindex\fR. | |
378 | The first two elements of the list give the x and y coordinates of | |
379 | the upper-left corner of the screen area covered by the character | |
380 | (in pixels relative to the widget) and the last two elements give | |
381 | the width and height of the character, in pixels. | |
382 | The bounding box may refer to a region outside the visible area | |
383 | of the window. | |
384 | .IP "\fI$entry\fR\->\fBdelete\fR(\fIfirst, \fR?\fIlast\fR?)" 4 | |
385 | .IX Item "$entry->delete(first, ?last?)" | |
386 | Returns the current value of the configuration option given | |
387 | by \fIoption\fR. | |
388 | \&\fIOption\fR may have any of the values accepted by the \fBentry\fR | |
389 | command. | |
390 | .IP "\fI$entry\fR\->\fBconfigure\fR(?\fIoption\fR?, ?\fIvalue, option, value, ...\fR?)" 4 | |
391 | .IX Item "$entry->configure(?option?, ?value, option, value, ...?)" | |
392 | Query or modify the configuration options of the widget. | |
393 | If no \fIoption\fR is specified, returns a list describing all of | |
394 | the available options for \f(CW$entry\fR (see Tk::configure for | |
395 | information on the format of this list). If \fIoption\fR is specified | |
396 | with no \fIvalue\fR, then the command returns a list describing the | |
397 | one named option (this list will be identical to the corresponding | |
398 | sublist of the value returned if no \fIoption\fR is specified). If | |
399 | one or more \fIoption-value\fR pairs are specified, then the command | |
400 | modifies the given widget option(s) to have the given value(s); in | |
401 | this case the command returns an empty string. | |
402 | \&\fIOption\fR may have any of the values accepted by the \fBentry\fR | |
403 | command. | |
404 | .IP "\fI$entry\fR\->\fBdelete\fR(\fIfirst, \fR?\fIlast\fR?)" 4 | |
405 | .IX Item "$entry->delete(first, ?last?)" | |
406 | Delete one or more elements of the entry. | |
407 | \&\fIFirst\fR is the index of the first character to delete, and | |
408 | \&\fIlast\fR is the index of the character just after the last | |
409 | one to delete. | |
410 | If \fIlast\fR isn't specified it defaults to \fIfirst\fR+1, | |
411 | i.e. a single character is deleted. | |
412 | This method returns an empty string. | |
413 | .IP "\fI$entry\fR\->\fBget\fR" 4 | |
414 | .IX Item "$entry->get" | |
415 | Returns the entry's string. | |
416 | .IP "\fI$entry\fR\->\fBicursor\fR(\fIindex\fR)" 4 | |
417 | .IX Item "$entry->icursor(index)" | |
418 | Arrange for the insertion cursor to be displayed just before the character | |
419 | given by \fIindex\fR. Returns an empty string. | |
420 | .IP "\fI$entry\fR\->\fBindex\fR(\fIindex\fR)" 4 | |
421 | .IX Item "$entry->index(index)" | |
422 | Returns the numerical index corresponding to \fIindex\fR. | |
423 | .IP "\fI$entry\fR\->\fBinsert\fR(\fIindex, string\fR)" 4 | |
424 | .IX Item "$entry->insert(index, string)" | |
425 | Insert the characters of \fIstring\fR just before the character | |
426 | indicated by \fIindex\fR. Returns an empty string. | |
427 | .IP "\fI$entry\fR\->\fBscan\fR(\fIoption, args\fR)" 4 | |
428 | .IX Item "$entry->scan(option, args)" | |
429 | .PD 0 | |
430 | .IP "\fI$entry\fR\->\fBscan\fR\fIOption\fR(\fIargs\fR)" 4 | |
431 | .IX Item "$entry->scanOption(args)" | |
432 | .PD | |
433 | This method is used to implement scanning on entries. It has | |
434 | two forms, depending on \fIOption\fR: | |
435 | .RS 4 | |
436 | .IP "\fI$entry\fR\->\fBscanMark\fR(\fIx\fR)" 8 | |
437 | .IX Item "$entry->scanMark(x)" | |
438 | Records \fIx\fR and the current view in the entry widget; used in | |
439 | conjunction with later \fBscanDragto\fR methods. Typically this | |
440 | method is associated with a mouse button press in the widget. It | |
441 | returns an empty string. | |
442 | .IP "\fI$entry\fR\->\fBscanDragto\fR(\fIx\fR)" 8 | |
443 | .IX Item "$entry->scanDragto(x)" | |
444 | This method computes the difference between its \fIx\fR argument | |
445 | and the \fIx\fR argument to the last \fBscanMark\fR method for | |
446 | the widget. It then adjusts the view left or right by 10 times the | |
447 | difference in x\-coordinates. This method is typically associated | |
448 | with mouse motion events in the widget, to produce the effect of | |
449 | dragging the entry at high speed through the widget. The return | |
450 | value is an empty string. | |
451 | .RE | |
452 | .RS 4 | |
453 | .RE | |
454 | .IP "\fI$entry\fR\->\fBselection\fR(\fIoption, arg\fR)" 4 | |
455 | .IX Item "$entry->selection(option, arg)" | |
456 | .PD 0 | |
457 | .IP "\fI$entry\fR\->\fBselection\fR\fIOption\fR(\fIarg\fR)" 4 | |
458 | .IX Item "$entry->selectionOption(arg)" | |
459 | .PD | |
460 | This method is used to adjust the selection within an entry. It | |
461 | has several forms, depending on \fIOption\fR: | |
462 | .RS 4 | |
463 | .IP "\fI$entry\fR\->\fBselectionAdjust\fR(\fIindex\fR)" 8 | |
464 | .IX Item "$entry->selectionAdjust(index)" | |
465 | Locate the end of the selection nearest to the character given by | |
466 | \&\fIindex\fR, and adjust that end of the selection to be at \fIindex\fR | |
467 | (i.e including but not going beyond \fIindex\fR). The other | |
468 | end of the selection is made the anchor point for future | |
469 | \&\fBselectionTo\fR methods. If the selection | |
470 | isn't currently in the entry, then a new selection is created to | |
471 | include the characters between \fIindex\fR and the most recent | |
472 | selection anchor point, inclusive. | |
473 | Returns an empty string. | |
474 | .IP "\fI$entry\fR\->\fBselectionClear\fR" 8 | |
475 | .IX Item "$entry->selectionClear" | |
476 | Clear the selection if it is currently in this widget. If the | |
477 | selection isn't in this widget then the method has no effect. | |
478 | Returns an empty string. | |
479 | .IP "\fI$entry\fR\->\fBselectionFrom\fR(\fIindex\fR)" 8 | |
480 | .IX Item "$entry->selectionFrom(index)" | |
481 | Set the selection anchor point to just before the character | |
482 | given by \fIindex\fR. Doesn't change the selection. | |
483 | Returns an empty string. | |
484 | .IP "\fI$entry\fR\->\fBselectionPresent\fR" 8 | |
485 | .IX Item "$entry->selectionPresent" | |
486 | Returns 1 if there is are characters selected in the entry, | |
487 | 0 if nothing is selected. | |
488 | .IP "\fI$entry\fR\->\fBselectionRange\fR(\fIstart, \fR\fIend\fR)" 8 | |
489 | .IX Item "$entry->selectionRange(start, end)" | |
490 | Sets the selection to include the characters starting with | |
491 | the one indexed by \fIstart\fR and ending with the one just | |
492 | before \fIend\fR. | |
493 | If \fIend\fR refers to the same character as \fIstart\fR or an | |
494 | earlier one, then the entry's selection is cleared. | |
495 | .IP "\fI$entry\fR\->\fBselectionTo\fR(\fIindex\fR)" 8 | |
496 | .IX Item "$entry->selectionTo(index)" | |
497 | If \fIindex\fR is before the anchor point, set the selection | |
498 | to the characters from \fIindex\fR up to but not including | |
499 | the anchor point. | |
500 | If \fIindex\fR is the same as the anchor point, do nothing. | |
501 | If \fIindex\fR is after the anchor point, set the selection | |
502 | to the characters from the anchor point up to but not including | |
503 | \&\fIindex\fR. | |
504 | The anchor point is determined by the most recent \fBselectionFrom\fR | |
505 | or \fBselectionAdjust\fR method in this widget. | |
506 | If the selection isn't in this widget then a new selection is | |
507 | created using the most recent anchor point specified for the widget. | |
508 | Returns an empty string. | |
509 | .RE | |
510 | .RS 4 | |
511 | .RE | |
512 | .IP "\fI$entry\fR\->\fBvalidate\fR" 4 | |
513 | .IX Item "$entry->validate" | |
514 | This command is used to force an evaluation of the \fBvalidateCommand\fR | |
515 | independent of the conditions specified by the \fBvalidate\fR option. It | |
516 | returns 0 or 1. | |
517 | .IP "\fI$entry\fR\->\fBxview\fR(\fIargs\fR)" 4 | |
518 | .IX Item "$entry->xview(args)" | |
519 | This command is used to query and change the horizontal position of the | |
520 | text in the widget's window. It can take any of the following | |
521 | forms: | |
522 | .RS 4 | |
523 | .IP "\fI$entry\fR\->\fBxview\fR" 8 | |
524 | .IX Item "$entry->xview" | |
525 | Returns a list containing two elements. | |
526 | Each element is a real fraction between 0 and 1; together they describe | |
527 | the horizontal span that is visible in the window. | |
528 | For example, if the first element is .2 and the second element is .7, | |
529 | 20% of the entry's text is off-screen to the left, the middle 50% is visible | |
530 | in the window, and 30% of the text is off-screen to the right. | |
531 | These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR | |
532 | option. | |
533 | .IP "\fI$entry\fR\->\fBxview\fR(\fIindex\fR)" 8 | |
534 | .IX Item "$entry->xview(index)" | |
535 | Adjusts the view in the window so that the character given by \fIindex\fR | |
536 | is displayed at the left edge of the window. | |
537 | .IP "\fI$entry\fR\->\fBxviewMoveto\fR(\fIfraction\fR)" 8 | |
538 | .IX Item "$entry->xviewMoveto(fraction)" | |
539 | Adjusts the view in the window so that the character \fIfraction\fR of the | |
540 | way through the text appears at the left edge of the window. | |
541 | \&\fIFraction\fR must be a fraction between 0 and 1. | |
542 | .IP "\fI$entry\fR\->\fBxviewScroll\fR(\fInumber, what\fR)" 8 | |
543 | .IX Item "$entry->xviewScroll(number, what)" | |
544 | This method shifts the view in the window left or right according to | |
545 | \&\fInumber\fR and \fIwhat\fR. | |
546 | \&\fINumber\fR must be an integer. | |
547 | \&\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation | |
548 | of one of these. | |
549 | If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by | |
550 | \&\fInumber\fR average-width characters on the display; if it is | |
551 | \&\fBpages\fR then the view adjusts by \fInumber\fR screenfuls. | |
552 | If \fInumber\fR is negative then characters farther to the left | |
553 | become visible; if it is positive then characters farther to the right | |
554 | become visible. | |
555 | .RE | |
556 | .RS 4 | |
557 | .SH "DEFAULT BINDINGS" | |
558 | .IX Header "DEFAULT BINDINGS" | |
559 | Tk automatically creates class bindings for entries that give them | |
560 | the following default behavior. | |
561 | In the descriptions below, ``word'' refers to a contiguous group | |
562 | of letters, digits, or ``_'' characters, or any single character | |
563 | other than these. | |
564 | .IP "[1]" 4 | |
565 | .IX Item "[1]" | |
566 | Clicking mouse button 1 positions the insertion cursor | |
567 | just before the character underneath the mouse cursor, sets the | |
568 | input focus to this widget, and clears any selection in the widget. | |
569 | Dragging with mouse button 1 strokes out a selection between | |
570 | the insertion cursor and the character under the mouse. | |
571 | .IP "[2]" 4 | |
572 | .IX Item "[2]" | |
573 | Double-clicking with mouse button 1 selects the word under the mouse | |
574 | and positions the insertion cursor at the beginning of the word. | |
575 | Dragging after a double click will stroke out a selection consisting | |
576 | of whole words. | |
577 | .IP "[3]" 4 | |
578 | .IX Item "[3]" | |
579 | Triple-clicking with mouse button 1 selects all of the text in the | |
580 | entry and positions the insertion cursor before the first character. | |
581 | .IP "[4]" 4 | |
582 | .IX Item "[4]" | |
583 | The ends of the selection can be adjusted by dragging with mouse | |
584 | button 1 while the Shift key is down; this will adjust the end | |
585 | of the selection that was nearest to the mouse cursor when button | |
586 | 1 was pressed. | |
587 | If the button is double-clicked before dragging then the selection | |
588 | will be adjusted in units of whole words. | |
589 | .IP "[5]" 4 | |
590 | .IX Item "[5]" | |
591 | Clicking mouse button 1 with the Control key down will position the | |
592 | insertion cursor in the entry without affecting the selection. | |
593 | .IP "[6]" 4 | |
594 | .IX Item "[6]" | |
595 | If any normal printing characters are typed in an entry, they are | |
596 | inserted at the point of the insertion cursor. | |
597 | .IP "[7]" 4 | |
598 | .IX Item "[7]" | |
599 | The view in the entry can be adjusted by dragging with mouse button 2. | |
600 | If mouse button 2 is clicked without moving the mouse, the selection | |
601 | is copied into the entry at the position of the mouse cursor. | |
602 | .IP "[8]" 4 | |
603 | .IX Item "[8]" | |
604 | If the mouse is dragged out of the entry on the left or right sides | |
605 | while button 1 is pressed, the entry will automatically scroll to | |
606 | make more text visible (if there is more text off-screen on the side | |
607 | where the mouse left the window). | |
608 | .IP "[9]" 4 | |
609 | .IX Item "[9]" | |
610 | The Left and Right keys move the insertion cursor one character to the | |
611 | left or right; they also clear any selection in the entry and set | |
612 | the selection anchor. | |
613 | If Left or Right is typed with the Shift key down, then the insertion | |
614 | cursor moves and the selection is extended to include the new character. | |
615 | Control-Left and Control-Right move the insertion cursor by words, and | |
616 | Control-Shift-Left and Control-Shift-Right move the insertion cursor | |
617 | by words and also extend the selection. | |
618 | Control-b and Control-f behave the same as Left and Right, respectively. | |
619 | Meta-b and Meta-f behave the same as Control-Left and Control\-Right, | |
620 | respectively. | |
621 | .IP "[10]" 4 | |
622 | .IX Item "[10]" | |
623 | The Home key, or Control\-a, will move the insertion cursor to the | |
624 | beginning of the entry and clear any selection in the entry. | |
625 | Shift-Home moves the insertion cursor to the beginning of the entry | |
626 | and also extends the selection to that point. | |
627 | .IP "[11]" 4 | |
628 | .IX Item "[11]" | |
629 | The End key, or Control\-e, will move the insertion cursor to the | |
630 | end of the entry and clear any selection in the entry. | |
631 | Shift-End moves the cursor to the end and extends the selection | |
632 | to that point. | |
633 | .IP "[12]" 4 | |
634 | .IX Item "[12]" | |
635 | The Select key and Control-Space set the selection anchor to the position | |
636 | of the insertion cursor. They don't affect the current selection. | |
637 | Shift-Select and Control-Shift-Space adjust the selection to the | |
638 | current position of the insertion cursor, selecting from the anchor | |
639 | to the insertion cursor if there was not any selection previously. | |
640 | .IP "[13]" 4 | |
641 | .IX Item "[13]" | |
642 | Control\-/ selects all the text in the entry. | |
643 | .IP "[14]" 4 | |
644 | .IX Item "[14]" | |
645 | Control\-\e clears any selection in the entry. | |
646 | .IP "[15]" 4 | |
647 | .IX Item "[15]" | |
648 | The F16 key (labelled Copy on many Sun workstations) or Meta-w | |
649 | copies the selection in the widget to the clipboard, if there is a selection. | |
650 | .IP "[16]" 4 | |
651 | .IX Item "[16]" | |
652 | The F20 key (labelled Cut on many Sun workstations) or Control-w | |
653 | copies the selection in the widget to the clipboard and deletes | |
654 | the selection. | |
655 | If there is no selection in the widget then these keys have no effect. | |
656 | .IP "[17]" 4 | |
657 | .IX Item "[17]" | |
658 | The F18 key (labelled Paste on many Sun workstations) or Control-y | |
659 | inserts the contents of the clipboard at the position of the | |
660 | insertion cursor. | |
661 | .IP "[18]" 4 | |
662 | .IX Item "[18]" | |
663 | The Delete key deletes the selection, if there is one in the entry. | |
664 | If there is no selection, it deletes the character to the right of | |
665 | the insertion cursor. | |
666 | .IP "[19]" 4 | |
667 | .IX Item "[19]" | |
668 | The BackSpace key and Control-h delete the selection, if there is one | |
669 | in the entry. | |
670 | If there is no selection, it deletes the character to the left of | |
671 | the insertion cursor. | |
672 | .IP "[20]" 4 | |
673 | .IX Item "[20]" | |
674 | Control-d deletes the character to the right of the insertion cursor. | |
675 | .IP "[21]" 4 | |
676 | .IX Item "[21]" | |
677 | Meta-d deletes the word to the right of the insertion cursor. | |
678 | .IP "[22]" 4 | |
679 | .IX Item "[22]" | |
680 | Control-k deletes all the characters to the right of the insertion | |
681 | cursor. | |
682 | .IP "[23]" 4 | |
683 | .IX Item "[23]" | |
684 | Control-t reverses the order of the two characters to the right of | |
685 | the insertion cursor. | |
686 | .Sp | |
687 | If the entry is disabled using the \fB\-state\fR option, then the entry's | |
688 | view can still be adjusted and text in the entry can still be selected, | |
689 | but no insertion cursor will be displayed and no text modifications will | |
690 | take place. | |
691 | .Sp | |
692 | The behavior of entries can be changed by defining new bindings for | |
693 | individual widgets or by redefining the class bindings. | |
694 | .RE | |
695 | .RS 4 | |
696 | .SH "KEYWORDS" | |
697 | .IX Header "KEYWORDS" | |
698 | entry, widget |