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:

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.