The Entry Widget

---

	Practical Programming in Tcl & Tk, Third Edition By Brent B. Welch
	Table of Contents
	Chapter 31.  The Entry Widget

---

Table 31-1 gives the bindings for entry widgets. When the table lists two sequences, they are equivalent. The table does not list all the right arrow key bindings; there are corresponding bindings for the left and right arrow keys.

Table 31-1. Entry bindings.

<Button-1>	Sets the insert point and starts a selection.
<B1-Motion>	Drags out a selection.
<Double-Button-1>	Selects a word.
<Triple-Button-1>	Selects all text in the entry.
<Shift-B1-Motion>	Adjusts the ends of the selection.
<Control-Button-1>	Sets insert point, leaving selection as is.
<Button-2>	Pastes selection at the insert cursor.
<B2-Motion>	Scrolls horizontally.
<Left> <Control-b>	Moves insert cursor one character left and starts the selection.
<Shift-Left>	Moves cursor left and extends the selection.
<Control-Left>	Moves cursor left one word and starts the selection.
<Meta-b>	Same as <Control-Left>.
<Control-Shift-Left>	Moves cursor left one word and extends the selection.
<Right> <Control-f>	Moves right one character.
<Meta-f> <Control-Right>	Moves right one word.
<Home> <Control-a>	Moves cursor to beginning of entry.
<Shift-Home>	Moves cursor to beginning and extends the selection.
<End> <Control-e>	Moves cursor to end of entry.
<Shift-End>	Moves cursor to end and extends the selection.
<Select> <Control-Space>	Anchors the selection at the insert cursor.
<Shift-Select> <Control-Shift-Space>	Adjusts the selection to the insert cursor.
<Control-slash>	Selects all the text in the entry.
<Control-backslash>	Clears the selection in the entry.
<Delete>	Deletes the selection or deletes next character.
<Backspace> <Control-h>	Deletes the selection or deletes previous character.
<Control-d>	Deletes next character.
<Meta-d>	Deletes next word.
<Control-k>	Deletes to the end of the entry.
<Control-w>	Deletes previous word.
<Control-x>	Deletes the section, if it exists.
<Control-t>	Transposes characters.

Entry Attributes

Table 31-2 lists the entry widget attributes. The table lists the resource name, which has capitals at internal word boundaries. In Tcl commands these options are specified with a dash and are all lowercase.

Table 31-2. Entry attribute resource names.

background	Background color (also bg).
borderWidth	Extra space around the edge of the text (also bd).
cursor	Cursor to display when mouse is over the widget.
exportSelection	If true, selected text is exported via the X selection mechanism.
font	Font for the text.
foreground	Foreground color (also fg).
highlightBackground	Focus highlight color when widget does not have focus.
highlightColor	Focus highlight color when widget has focus.
highlightThickness	Thickness of focus highlight rectangle.
insertBackground	Background for area covered by insert cursor.
insertBorderWidth	Width of cursor border. Non-zero for 3D effect.
insertOffTime	Time, in milliseconds the insert cursor blinks off.
insertOnTime	Time, in milliseconds the insert cursor blinks on.
insertWidth	Width of insert cursor. Default is 2.
justify	Text justification: left, right, center.
relief	flat, sunken, raised, groove, solid or ridge.
selectBackground	Background color of selection.
selectForeground	Foreground color of selection.
selectBorderWidth	Width of selection border. Nonzero for 3D effect.
show	A character (e.g., *) to display instead of contents.
state	State: disabled (read-only) or normal.
takeFocus	Controls focus changes from keyboard traversal.
textVariable	Name of Tcl variable.
width	Width, in characters.
xScrollCommand	Connects entry to a scrollbar.

Programming Entry Widgets

The default bindings for entry widgets are fairly good. However, you can completely control the entry with a set of widget operations for inserting, deleting, selecting, and scrolling. The operations involve addressing character positions called indices. The indices count from zero. The entry defines some symbolic indices such as end. The index corresponding to an X coordinate is specified with @xcoord, such as @26. Table 31-3 lists the formats for indices.

Table 31-3. Entry indices.

0	Index of the first character.
anchor	The index of the anchor point of the selection.
end	Index just after the last character.
number	Index a character, counting from zero.
insert	The character right after the insertion cursor.
sel.first	The first character in the selection.
sel.last	The character just after the last character in the selection.
@xcoord	The character under the specified X coordinate.

Table 31-4 summarizes the operations on entry widgets. In the table, $w is an entry widget.

Table 31-4. Entry operations.

$w cget option	Returns the value of the configuration option.
$w configure ...	Queries or modifies the widget configuration.
$w delete first ?last?	Deletes the characters from first to last, not including the character at last. The character at first is deleted if last is not specified.
$w get	Returns the string in the entry.
$w icursor index	Moves the insert cursor.
$w index index	Returns the numerical index corresponding to index.
$w insert index string	Inserts the string at the given index.
$w scan mark x	Starts a scroll operation. x is a screen coordinate.
$w scan dragto x	Scrolls from previous mark position.
$w select adjust index	Moves the boundary of an existing selection.
$w select clear	Clears the selection.
$w select from index	Sets the anchor position for the selection.
$w select present	Returns 1 if there is a selection in the entry.
$w select range start end	Selects the characters from start to the one just before end.
$w select to index	Extends the selection.
$w xview	Returns the offset and span of visible contents. These are both real numbers between 0 and 1.0.
$w xview index	Shifts the display so the character at index is at the left edge of the display.
$w xview moveto fraction	Shifts the display so that fraction of the contents are off the left edge of the display.
$w xview scroll num what	Scrolls the contents by the specified number of what, which can be units or pages.

For example, the binding for <Button-1> includes the following commands:

 %W icursor @%x %W select from @%x if {%W cget -state] == "normal"} {focus %W} 

Recall that the % triggers substitutions in binding commands, and that %W is replaced with the widget pathname and %x is replaced with the X coordinate of the mouse event. Chapter 26 describes bindings and these substitutions in detail. These commands set the insert point to the point of the mouse click by using the @%x index, which will be turned into something like @17 when the binding is invoked. The binding also starts a selection. If the entry is not in the disabled state, then keyboard focus is given to the entry so that it gets KeyPress events.

---

Top